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

# Workspaces

Manage workspaces, members, roles, invitations, and preferences.

## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/preferences

> Get Workspace Preferences

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Workspaces","description":"Manage workspaces, members, roles, invitations, and preferences."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1WorkspacePreferences":{"type":"object","properties":{"name":{"type":"string","title":"The resource name of the workspace preferences.\nFormat: `organizations/{organization}/workspaces/{workspace}/preferences`"},"support_team_access":{"type":"boolean","description":"Support team access to workspace for debugging issues."},"general":{"$ref":"#/components/schemas/v1GeneralPreferences"},"show_bounding_boxes":{"type":"boolean","description":"Whether document viewers in the workspace draw bounding boxes around\nextracted values; true by default."}},"description":"Represents workspace-specific settings or preferences."},"v1GeneralPreferences":{"type":"object","properties":{"time_zone":{"type":"string","description":"The time zone preference.\nShould be an IANA timezone identifier (e.g., \"America/New_York\", \"Europe/London\", \"UTC\")."},"time_format":{"$ref":"#/components/schemas/v1TimeFormat"},"date_format":{"$ref":"#/components/schemas/v1DateFormat"},"decimal_symbol":{"$ref":"#/components/schemas/v1DecimalSymbol"},"decimal_places":{"type":"integer","format":"int32","description":"The number of digits after decimal point. Valid range [0, 10].\n\nMarked `optional` so that 0 (a legitimate user choice meaning\n\"integer display\") can be distinguished from \"field not set\". Wire\nformat is identical to a plain `int32` in proto3 — old clients that\nomit the field still decode as absent on the server."},"measurement_system":{"$ref":"#/components/schemas/v1MeasurementSystem"},"week_start":{"$ref":"#/components/schemas/v1WeekStart"},"language_code":{"type":"string","description":"The user-facing language as a BCP-47 locale code (e.g. `en`, `es`, `zh-Hans`).\nEmpty string indicates inherit-from-parent-scope or system default."}},"description":"General preferences for display and formatting.\nUsed by both workspace and organization preferences, and embedded in\nUserPreferences to allow user-level overrides for every field."},"v1TimeFormat":{"type":"string","enum":["TIME_FORMAT_UNSPECIFIED","TIME_FORMAT_12_HOUR","TIME_FORMAT_24_HOUR"],"default":"TIME_FORMAT_UNSPECIFIED","description":"Supported time formats.\n\n - TIME_FORMAT_UNSPECIFIED: Unspecified time format.\n - TIME_FORMAT_12_HOUR: 12-hour format (1:00 PM).\n - TIME_FORMAT_24_HOUR: 24-hour format (13:00)."},"v1DateFormat":{"type":"string","enum":["DATE_FORMAT_UNSPECIFIED","DATE_FORMAT_DD_MM_YYYY_SLASH","DATE_FORMAT_MM_DD_YYYY_SLASH","DATE_FORMAT_YYYY_MM_DD_DASH","DATE_FORMAT_DD_MM_YYYY_DASH","DATE_FORMAT_MM_DD_YYYY_DASH","DATE_FORMAT_YYYY_MM_DD_SLASH","DATE_FORMAT_DD_MM_YYYY_DOT","DATE_FORMAT_MM_DD_YYYY_DOT","DATE_FORMAT_YYYY_MM_DD_DOT","DATE_FORMAT_DD_MMM_YYYY","DATE_FORMAT_MMM_DD_YYYY","DATE_FORMAT_DD_MMMM_YYYY","DATE_FORMAT_MMMM_DD_YYYY"],"default":"DATE_FORMAT_UNSPECIFIED","description":"Supported date formats.\n\n - DATE_FORMAT_UNSPECIFIED: Unspecified date format.\n - DATE_FORMAT_DD_MM_YYYY_SLASH: DD/MM/YYYY format.\n - DATE_FORMAT_MM_DD_YYYY_SLASH: MM/DD/YYYY format.\n - DATE_FORMAT_YYYY_MM_DD_DASH: YYYY-MM-DD format (ISO 8601).\n - DATE_FORMAT_DD_MM_YYYY_DASH: DD-MM-YYYY format.\n - DATE_FORMAT_MM_DD_YYYY_DASH: MM-DD-YYYY format.\n - DATE_FORMAT_YYYY_MM_DD_SLASH: YYYY/MM/DD format.\n - DATE_FORMAT_DD_MM_YYYY_DOT: DD.MM.YYYY format (European style).\n - DATE_FORMAT_MM_DD_YYYY_DOT: MM.DD.YYYY format.\n - DATE_FORMAT_YYYY_MM_DD_DOT: YYYY.MM.DD format.\n - DATE_FORMAT_DD_MMM_YYYY: DD MMM YYYY format (e.g., 15 Jan 2024).\n - DATE_FORMAT_MMM_DD_YYYY: MMM DD, YYYY format (e.g., Jan 15, 2024).\n - DATE_FORMAT_DD_MMMM_YYYY: DD MMMM YYYY format (e.g., 15 January 2024).\n - DATE_FORMAT_MMMM_DD_YYYY: MMMM DD, YYYY format (e.g., January 15, 2024)."},"v1DecimalSymbol":{"type":"string","enum":["DECIMAL_SYMBOL_UNSPECIFIED","DECIMAL_SYMBOL_PERIOD","DECIMAL_SYMBOL_COMMA"],"default":"DECIMAL_SYMBOL_UNSPECIFIED","description":"Supported decimal symbols.\n\n - DECIMAL_SYMBOL_UNSPECIFIED: Unspecified decimal symbol.\n - DECIMAL_SYMBOL_PERIOD: Period (.) as decimal separator.\n - DECIMAL_SYMBOL_COMMA: Comma (,) as decimal separator."},"v1MeasurementSystem":{"type":"string","enum":["MEASUREMENT_SYSTEM_UNSPECIFIED","MEASUREMENT_SYSTEM_METRIC","MEASUREMENT_SYSTEM_IMPERIAL"],"default":"MEASUREMENT_SYSTEM_UNSPECIFIED","description":"Supported measurement systems.\n\n - MEASUREMENT_SYSTEM_UNSPECIFIED: Unspecified measurement system.\n - MEASUREMENT_SYSTEM_METRIC: Metric system.\n - MEASUREMENT_SYSTEM_IMPERIAL: Imperial system."},"v1WeekStart":{"type":"string","enum":["WEEK_START_UNSPECIFIED","WEEK_START_SUNDAY","WEEK_START_MONDAY"],"default":"WEEK_START_UNSPECIFIED","description":"- WEEK_START_UNSPECIFIED: Unspecified — caller should treat as \"use scope default\" (typically Sunday).\n - WEEK_START_SUNDAY: Week starts on Sunday.\n - WEEK_START_MONDAY: Week starts on Monday.","title":"First day of the week, surfaced via GeneralPreferences.week_start."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/preferences":{"get":{"summary":"Get Workspace Preferences","operationId":"GetWorkspacePreferences","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1WorkspacePreferences"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Workspaces"]}}}}
```

## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/invites

> List Workspace User Invites

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Workspaces","description":"Manage workspaces, members, roles, invitations, and preferences."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ListWorkspaceUserInvitesResponse":{"type":"object","properties":{"invitations":{"type":"array","items":{"$ref":"#/components/schemas/v1UserInvitation"},"description":"The list of pending user invitations."},"next_page_token":{"type":"string","description":"A token to retrieve the next page of results.\nPass this value in the page_token field in the subsequent call to\nListWorkspaceUserInvites to get the next page of results."}},"description":"Response message for ListWorkspaceUserInvites."},"v1UserInvitation":{"type":"object","properties":{"email":{"type":"string","description":"The user's email address."},"invitation_id":{"type":"string","description":"The invitation ID."},"role_template_ids":{"type":"array","items":{"type":"string"},"title":"Role template IDs assigned by this invitation."},"workspace_display_name":{"type":"string","description":"Workspace display name the invite is scoped to. Empty when the invite is\norg-level (no specific workspace)."},"create_time":{"type":"string","format":"date-time","title":"Server-set creation timestamp, mirroring `Invitation.create_time`.","readOnly":true},"workspace_id":{"type":"string","title":"ID of the workspace the invite is scoped to, so clients can link to it\ninstead of matching on the non-unique `workspace_display_name`. Unset when\nthe invite is org-level.","readOnly":true},"roles":{"type":"array","items":{"$ref":"#/components/schemas/v1InvitationRole"},"title":"Every role the invite grants, with its display title. Supersedes\n`role_template_ids` for display: that field lists built-in templates only,\nwhile this also covers workspace custom roles.","readOnly":true}},"description":"A UserInvitation represents a pending invitation summary returned by\n`ListOrganizationUserInvites` / `ListWorkspaceUserInvites`.\n\nPreviously this message only carried `email` and `invitation_id`; the\nadmin Invitations table in the v2.2 mocks needs role(s) and workspace too,\nso those are surfaced here directly to avoid one `GetInvitation` per row."},"v1InvitationRole":{"type":"object","properties":{"id":{"type":"string","title":"Identifies the role. For a built-in template this is the same bare id as in\n`UserInvitation.role_template_ids` (e.g. \"agora.viewer\"). For a workspace\ncustom role it is the resource name invites accept:\n  organizations/{organization}/workspaces/{workspace}/customRoles/{custom_role}"},"title":{"type":"string","description":"Human-readable title of the role. Empty if the role can no longer be\nresolved, in which case clients should fall back to formatting `id`."}},"description":"A role granted by an invitation, as listed on `UserInvitation`."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/invites":{"get":{"summary":"List Workspace User Invites","operationId":"ListWorkspaceUserInvites","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ListWorkspaceUserInvitesResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page_size","description":"The maximum number of invitations to return.\nIf unspecified, at most 50 invitations will be returned.\nThe maximum value is 1000; values above 1000 will be coerced to 1000.","in":"query","required":false,"schema":{"type":"integer","format":"int64"}},{"name":"page_token","description":"A page token, received from a previous ListWorkspaceUserInvites call.\nProvide this to retrieve the subsequent page.","in":"query","required":false,"schema":{"type":"string"}},{"name":"direction","description":"Optional filter by direction. Defaults to `INVITE`.\n\n - INVITATION_DIRECTION_UNSPECIFIED: Unspecified — treated as INVITE for backward compatibility.\n - INVITATION_DIRECTION_INVITE: Admin invites a user to join an org or workspace. (Default; pre-existing behavior.)\n - INVITATION_DIRECTION_REQUEST: User requests access to an org or workspace they can't currently reach\n(powers the No Access page's \"Request access\" button).","in":"query","required":false,"schema":{"type":"string","enum":["INVITATION_DIRECTION_UNSPECIFIED","INVITATION_DIRECTION_INVITE","INVITATION_DIRECTION_REQUEST"],"default":"INVITATION_DIRECTION_UNSPECIFIED"}}],"tags":["Workspaces"]}}}}
```

## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/roles

> List Workspace Roles

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Workspaces","description":"Manage workspaces, members, roles, invitations, and preferences."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ListWorkspaceRolesResponse":{"type":"object","properties":{"roles":{"type":"array","items":{"$ref":"#/components/schemas/v1Role"},"description":"The list of roles in the workspace.\nIncludes both system-defined role templates (named roleTemplates/{id})\nand the workspace's custom roles (named\norganizations/{org}/workspaces/{ws}/customRoles/{id}, with `custom` set)."},"next_page_token":{"type":"string","description":"A token to retrieve the next page of results.\nPass this value in the page_token field in the subsequent call to\nListWorkspaceRoles to get the next page of results."}},"description":"Response message for ListWorkspaceRoles."},"v1Role":{"type":"object","properties":{"name":{"type":"string","title":"Resource name of the role.\nFormat: organizations/{organization}/roles/{role} (org-level)\nFormat: organizations/{organization}/workspaces/{workspace}/roles/{role} (workspace-level)","description":"List responses also use this message for entries that are not concrete\nrole instances, in which case `name` carries the referenced resource:\n  roleTemplates/{role_template} for system-defined templates\n  organizations/{organization}/workspaces/{workspace}/customRoles/{custom_role}\n    for workspace custom roles, which additionally set `custom`.\nThese are not declared as patterns above because AIP-123 requires every\npattern's final segment to contain this resource's own singular."},"title":{"type":"string","description":"Human-readable title of the role (e.g., \"Administrator\", \"Editor\")."},"description":{"type":"string","description":"Description of what this role grants."},"permissions":{"type":"array","items":{"type":"string"},"title":"List of permission strings this role grants.\nFormat: \"{action}:{resource_path}\" (e.g., \"GET:/api/v1/me\")","readOnly":true,"description":"Superseded by `permission_details`, which carries these same strings plus\ntheir display metadata; this field is slated for removal in the next major\nversion. It is not yet marked `deprecated` because clients cannot migrate\nuntil Agora populates `permission_details` — do that first, then flip the\noption, then remove the field."},"permission_description":{"type":"string","description":"Description of the permissions granted by this role."},"custom":{"type":"boolean","description":"True when this entry is a workspace-scoped custom role rather than a\nsystem-defined role template. Lets clients tell the two apart without\nparsing `name`."},"permission_details":{"type":"array","items":{"$ref":"#/components/schemas/v1RolePermission"},"description":"The permissions this role grants, with the display metadata needed to render\nthem. Supersedes `permissions`, which carries the same strings without it.\n\n`RolePermission.permission` is self-sufficient — it is the same\n\"{action}:{resource_path}\" string — so a client needs only this field.\n\nKeyed by the permission string rather than positional: entries correspond to\n`permissions` by `RolePermission.permission`, not by index. An entry may be\nabsent when a permission has no backing template metadata, so a client must\nfall back to the raw `permissions` string rather than assume coverage.","readOnly":true}},"description":"A Role represents a concrete, assignable role that can be assigned to users.\nRoles can be created from RoleTemplates or as standalone custom roles.","required":["title"]},"v1RolePermission":{"type":"object","properties":{"permission":{"type":"string","title":"The permission this describes, matching an entry in `Role.permissions`.\nFormat: \"{action}:{resource_path}\" (e.g., \"GET:/api/v1/me\")"},"display_name":{"type":"string","description":"Human-readable name of the permission (e.g., \"me:read\").\nMirrors the permission template's display name."},"description":{"type":"string","description":"What this permission allows. May be empty; not every template sets one."}},"description":"Display metadata for one permission a role grants.\n\nCarries only the human-readable name and description: the action and resource\npath are already encoded in the `Role.permissions` string this joins to, so\nrepeating them would double the payload of the field it describes for no gain."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/roles":{"get":{"summary":"List Workspace Roles","operationId":"ListWorkspaceRoles","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ListWorkspaceRolesResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page_size","description":"The maximum number of roles to return.\nIf unspecified, at most 50 roles will be returned.\nThe maximum value is 1000; values above 1000 will be coerced to 1000.","in":"query","required":false,"schema":{"type":"integer","format":"int64"}},{"name":"page_token","description":"A page token, received from a previous ListWorkspaceRoles call.\nProvide this to retrieve the subsequent page.","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Workspaces"]}}}}
```

## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/users

> List Workspace Users

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Workspaces","description":"Manage workspaces, members, roles, invitations, and preferences."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ListWorkspaceUsersResponse":{"type":"object","properties":{"users":{"type":"array","items":{"$ref":"#/components/schemas/v1UserWithRoles"},"description":"The list of users in the workspace with their roles."},"next_page_token":{"type":"string","description":"A token to retrieve the next page of results.\nPass this value in the `page_token` field in the subsequent call to\n`ListWorkspaceUsers` to get the next page of results. If this field is\nempty, it means there are no more results."}},"description":"Response message for listing users in a workspace."},"v1UserWithRoles":{"type":"object","properties":{"user":{"$ref":"#/components/schemas/v1UserBasicInfo"},"roles":{"type":"array","items":{"$ref":"#/components/schemas/v1RoleBasicInfo"},"description":"The user's assigned roles.\nEach role includes its scope (organization or workspace)."},"workspace_ids":{"type":"array","items":{"type":"string"},"description":"IDs of workspaces in which the user has any active workspace-scoped role.\nEmpty if the user only holds org-scoped roles (which grant implicit access\nto all workspaces in the org). Used by Org-Settings Users tab to render the\n\"Workspaces\" column (\"2 workspaces\" / \"All workspaces\" / specific name)."}},"description":"A user with their assigned roles.\nThis type is reusable for both organization and workspace user listing APIs.\nThe RoleScope field in each role indicates whether the role is org-level or workspace-level."},"v1UserBasicInfo":{"type":"object","properties":{"name":{"type":"string","title":"The unique resource name of the user basic info.\nFormat: `organizations/{organization}/users/{user_basic_info}`"},"display_name":{"type":"string","description":"The user's display name."},"email":{"type":"string","description":"The user's email address."},"last_active_time":{"type":"string","format":"date-time","description":"The most recent timestamp the user was seen on an authenticated request.\nOutput-only; written debounced on auth events, so it is accurate to within\na few minutes rather than to the request.\nUnset when the user has not been seen since the field was introduced —\nthere is no backfill, so clients should render an em-dash rather than an epoch date.\nMirrors `User.last_active_time`; surfaced here so the Org/Workspace Settings\nUsers tables can render the \"Last active\" column from a single list call.","readOnly":true}},"description":"Contains basic information about a user.\nThis is a lightweight representation used when full user details are not needed."},"v1RoleBasicInfo":{"type":"object","properties":{"name":{"type":"string","description":"The role name (e.g., \"workspace-admin\", \"org-admin\", or custom role name)."},"role_scope":{"$ref":"#/components/schemas/v1RoleScope"}},"title":"Lightweight role information following the UserBasicInfo pattern.\nNote: RoleScope is imported from rbac.proto"},"v1RoleScope":{"type":"string","enum":["ROLE_SCOPE_UNSPECIFIED","ROLE_SCOPE_ORGANIZATION","ROLE_SCOPE_WORKSPACE"],"default":"ROLE_SCOPE_UNSPECIFIED","description":"Defines the scope at which a role can be applied.\n\n - ROLE_SCOPE_UNSPECIFIED: Unspecified role scope.\n - ROLE_SCOPE_ORGANIZATION: Role applies at the organization level.\n - ROLE_SCOPE_WORKSPACE: Role applies at the workspace level."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/users":{"get":{"summary":"List Workspace Users","operationId":"ListWorkspaceUsers","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ListWorkspaceUsersResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page_size","description":"The maximum number of users to return.\nIf unspecified, at most 50 users will be returned.\nThe maximum value is 1000; values above 1000 will be coerced to 1000.","in":"query","required":false,"schema":{"type":"integer","format":"int64"}},{"name":"page_token","description":"A page token, received from a previous `ListWorkspaceUsers` call.\nProvide this to retrieve the subsequent page.\nWhen paginating, all other parameters provided to `ListWorkspaceUsers` must match\nthe call that provided the page token.","in":"query","required":false,"schema":{"type":"string"}},{"name":"filter","description":"Optional filter string following AIP-160 filtering standards.\nSupported filter fields:\n- `display_name`: Filter by display name (case-insensitive partial match). Example: `display_name:\"john\"`\n- `email`: Filter by email address (case-insensitive partial match). Example: `email:\"kognitos.com\"`\n- `role`: Filter by role name (exact match, case-insensitive). Example: `role=\"Workspace Viewer\"`\n- `role_scope`: Filter by role scope. Values: \"organization\" or \"workspace\". Example: `role_scope=workspace`\n- `last_active_time`: Filter by last-active timestamp range using `>=`, `>`, `<=` or `<`\n  against an RFC3339 timestamp. Example: `last_active_time >= \"2026-07-01T00:00:00Z\"`\n  Users with no last-active value are excluded by any range bound.\nFilters can be combined with AND: `display_name:\"john\" AND role=\"Admin\"`","in":"query","required":false,"schema":{"type":"string"}},{"name":"order_by","description":"Optional comma-separated list of fields to order by, following AIP-132.\nSupported fields: display_name, email, created_time, updated_time, last_active_time\nExample: \"display_name,created_time desc\"\nDefault ordering is by created_time descending if not specified.\nUsers with no `last_active_time` sort as least-recently-active: last under\n`last_active_time desc`, first under `last_active_time asc`.","in":"query","required":false,"schema":{"type":"string"}},{"name":"include_deactivated","description":"When true, includes deactivated (soft-deleted) users in the response.\nDefaults to false. Returned rows will have `User.state = USER_STATE_DEACTIVATED`.","in":"query","required":false,"schema":{"type":"boolean"}}],"tags":["Workspaces"]}}}}
```

## POST /api/v1/organizations/{organization\_id}/workspaces:countUsers

> Count Workspace Users

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Workspaces","description":"Manage workspaces, members, roles, invitations, and preferences."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1CountWorkspaceUsersResponse":{"type":"object","properties":{"workspace_user_counts":{"type":"object","additionalProperties":{"type":"integer","format":"int32"},"description":"A map of workspace IDs to their respective user counts.\nThe key is the workspace ID, and the value is the count of users in that workspace."}},"description":"Response message for counting users in specific workspaces."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"CountWorkspaceUsersBody":{"type":"object","properties":{"workspace_ids":{"type":"array","items":{"type":"string"},"title":"The list of workspace IDs to get user counts for.\nEach workspace_id should be the workspace identifier (not the full resource name).\nThe full workspace resource names will be constructed as:\norganizations/{organization}/workspaces/{workspace_id}"}},"description":"Request message for counting users in specific workspaces.","required":["workspace_ids"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces:countUsers":{"post":{"summary":"Count Workspace Users","operationId":"CountWorkspaceUsers","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1CountWorkspaceUsersResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CountWorkspaceUsersBody"}}},"required":true},"tags":["Workspaces"]}}}}
```

## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}

> Get Workspace

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Workspaces","description":"Manage workspaces, members, roles, invitations, and preferences."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1Workspace":{"type":"object","properties":{"name":{"type":"string","description":"The resource name of the workspace.\nFormat: organizations/{organization}/workspaces/{workspace}\nThis field is assigned by the server at creation and is immutable thereafter.\nClients may include this field in Get/Update/Delete requests to identify the resource."},"title":{"type":"string","description":"The user-defined display name for the workspace.\nThis corresponds to the `name` column in the database."},"workspace_icon":{"type":"string","description":"The workspace icon data.\nThis field contains the identifier of the workspace icon."},"workspace_icon_color":{"type":"string","description":"The color of the workspace icon."},"create_time":{"type":"string","format":"date-time","description":"The timestamp when the workspace was created.","readOnly":true},"update_time":{"type":"string","format":"date-time","description":"The timestamp when the workspace was last updated.","readOnly":true},"creator_display_name":{"type":"string","description":"The display name of the user who created the workspace.","readOnly":true},"creator_email":{"type":"string","description":"The email address of the user who created the workspace.","readOnly":true},"organization_display_name":{"type":"string","description":"The display name of the parent organization, surfaced output-only to avoid\na second GetOrganization round-trip from clients that render the workspace's\nparent on the workspace settings page.","readOnly":true},"icon_data_uri":{"type":"string","description":"The workspace icon as a data URI following RFC 2397 (custom image upload).\nFormat: data:[<mediatype>][;encoding],<data>\nServer-side max payload size: 10MB.\n\nCoexists with `workspace_icon` (preset id) + `workspace_icon_color`. If both\n`icon_data_uri` and `workspace_icon` are set on update, the custom image wins."},"workspace_type":{"$ref":"#/components/schemas/v1WorkspaceType"}},"description":"A Workspace is a container for agents within an organization.","required":["title"]},"v1WorkspaceType":{"type":"string","enum":["WORKSPACE_TYPE_UNSPECIFIED","WORKSPACE_TYPE_FINANCE","WORKSPACE_TYPE_REGULAR"],"default":"WORKSPACE_TYPE_UNSPECIFIED","description":"The category/type of a workspace, used to tailor workspace behavior.\n\nDeliberately kept in its own file with no imports. `WorkspaceType` is needed\nby both `types.proto` (on `Workspace`) and `rbac.proto` (on `RoleTemplate`),\nand `types.proto` already imports `rbac.proto` for `RoleScope` — so defining\nit in either of those files makes the other's import cyclic.\n\n - WORKSPACE_TYPE_UNSPECIFIED: Not set. Not a workspace category in its own right: a workspace created\nwithout an explicit type is treated as WORKSPACE_TYPE_REGULAR, and this\nvalue is not a valid member of `RoleTemplate.workspace_types`.\n - WORKSPACE_TYPE_FINANCE: Finance workspace.\n - WORKSPACE_TYPE_REGULAR: Regular (general-purpose, automation-oriented) workspace — the default\nfor workspaces created without an explicit type.\n\nNumbered after FINANCE only because renumbering an existing value is a\nwire break; REGULAR is the baseline kind, not a later addition."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}":{"get":{"summary":"Get Workspace","operationId":"GetWorkspace","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1Workspace"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Workspaces"]}}}}
```

## GET /api/v1/organizations/{organization\_id}/workspaces

> List Workspaces

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Workspaces","description":"Manage workspaces, members, roles, invitations, and preferences."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ListWorkspacesResponse":{"type":"object","properties":{"workspaces":{"type":"array","items":{"$ref":"#/components/schemas/v1Workspace"},"description":"The list of workspaces."},"next_page_token":{"type":"string","description":"A token to retrieve the next page of results.\nPass this value in the `page_token` field in the subsequent call to\n`ListWorkspaces` to get the next page of results. If this field is\nempty, it means there are no more results."}},"description":"Response message for listing workspaces."},"v1Workspace":{"type":"object","properties":{"name":{"type":"string","description":"The resource name of the workspace.\nFormat: organizations/{organization}/workspaces/{workspace}\nThis field is assigned by the server at creation and is immutable thereafter.\nClients may include this field in Get/Update/Delete requests to identify the resource."},"title":{"type":"string","description":"The user-defined display name for the workspace.\nThis corresponds to the `name` column in the database."},"workspace_icon":{"type":"string","description":"The workspace icon data.\nThis field contains the identifier of the workspace icon."},"workspace_icon_color":{"type":"string","description":"The color of the workspace icon."},"create_time":{"type":"string","format":"date-time","description":"The timestamp when the workspace was created.","readOnly":true},"update_time":{"type":"string","format":"date-time","description":"The timestamp when the workspace was last updated.","readOnly":true},"creator_display_name":{"type":"string","description":"The display name of the user who created the workspace.","readOnly":true},"creator_email":{"type":"string","description":"The email address of the user who created the workspace.","readOnly":true},"organization_display_name":{"type":"string","description":"The display name of the parent organization, surfaced output-only to avoid\na second GetOrganization round-trip from clients that render the workspace's\nparent on the workspace settings page.","readOnly":true},"icon_data_uri":{"type":"string","description":"The workspace icon as a data URI following RFC 2397 (custom image upload).\nFormat: data:[<mediatype>][;encoding],<data>\nServer-side max payload size: 10MB.\n\nCoexists with `workspace_icon` (preset id) + `workspace_icon_color`. If both\n`icon_data_uri` and `workspace_icon` are set on update, the custom image wins."},"workspace_type":{"$ref":"#/components/schemas/v1WorkspaceType"}},"description":"A Workspace is a container for agents within an organization.","required":["title"]},"v1WorkspaceType":{"type":"string","enum":["WORKSPACE_TYPE_UNSPECIFIED","WORKSPACE_TYPE_FINANCE","WORKSPACE_TYPE_REGULAR"],"default":"WORKSPACE_TYPE_UNSPECIFIED","description":"The category/type of a workspace, used to tailor workspace behavior.\n\nDeliberately kept in its own file with no imports. `WorkspaceType` is needed\nby both `types.proto` (on `Workspace`) and `rbac.proto` (on `RoleTemplate`),\nand `types.proto` already imports `rbac.proto` for `RoleScope` — so defining\nit in either of those files makes the other's import cyclic.\n\n - WORKSPACE_TYPE_UNSPECIFIED: Not set. Not a workspace category in its own right: a workspace created\nwithout an explicit type is treated as WORKSPACE_TYPE_REGULAR, and this\nvalue is not a valid member of `RoleTemplate.workspace_types`.\n - WORKSPACE_TYPE_FINANCE: Finance workspace.\n - WORKSPACE_TYPE_REGULAR: Regular (general-purpose, automation-oriented) workspace — the default\nfor workspaces created without an explicit type.\n\nNumbered after FINANCE only because renumbering an existing value is a\nwire break; REGULAR is the baseline kind, not a later addition."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces":{"get":{"summary":"List Workspaces","operationId":"ListWorkspaces","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ListWorkspacesResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page_size","description":"The maximum number of workspaces to return.\nIf unspecified, at most 50 workspaces will be returned.\nThe maximum value is 1000; values above 1000 will be coerced to 1000.","in":"query","required":false,"schema":{"type":"integer","format":"int64"}},{"name":"page_token","description":"A page token, received from a previous `ListWorkspaces` call.\nProvide this to retrieve the subsequent page.\nWhen paginating, all other parameters provided to `ListWorkspaces` must match\nthe call that provided the page token.","in":"query","required":false,"schema":{"type":"string"}},{"name":"filter","description":"Optional. A filter expression to constrain the workspaces returned.\nThe expression follows the syntax defined in AIP-160.\nSupported fields for filtering:\n  - `title`: The display name of the workspace\n\nExamples:\n  - `title = \"My Workspace\"` - exact match\n  - `title : \"workspace\"` - contains match (case-insensitive)","in":"query","required":false,"schema":{"type":"string"}},{"name":"order_by","description":"Optional comma-separated list of fields to order by, following AIP-132.\nSupported fields: title, create_time, update_time\nExample: \"title\", \"create_time desc\", \"update_time desc,title\"\nDefault ordering is by create_time descending if not specified.","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Workspaces"]}}}}
```

## GET /api/v1/me/organizations/{organization\_id}/workspaces

> Current User Organization Workspaces

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Workspaces","description":"Manage workspaces, members, roles, invitations, and preferences."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1CurrentUserOrganizationWorkspacesResponse":{"type":"object","properties":{"user_workspaces":{"type":"array","items":{"$ref":"#/components/schemas/v1Workspace"},"description":"The list of workspaces the current user has access to in the organization."},"next_page_token":{"type":"string","description":"A token to retrieve the next page of results.\nPass this value in the `page_token` field in the subsequent call to\n`CurrentUserOrganizationWorkspaces` to get the next page of results. If this field is\nempty, it means there are no more results."},"memberships":{"type":"array","items":{"$ref":"#/components/schemas/v1UserWorkspaceMembership"},"description":"The same workspaces as `user_workspaces`, enriched with the current user's\nrole(s) and join timestamp per workspace. Parallel to `user_workspaces` (same\nlength / order); existing callers continue to use `user_workspaces` for N-1.\nPowers the \"Organizations\" section on the user profile page."}},"description":"Response message for listing workspaces for the current user within a specific organization."},"v1Workspace":{"type":"object","properties":{"name":{"type":"string","description":"The resource name of the workspace.\nFormat: organizations/{organization}/workspaces/{workspace}\nThis field is assigned by the server at creation and is immutable thereafter.\nClients may include this field in Get/Update/Delete requests to identify the resource."},"title":{"type":"string","description":"The user-defined display name for the workspace.\nThis corresponds to the `name` column in the database."},"workspace_icon":{"type":"string","description":"The workspace icon data.\nThis field contains the identifier of the workspace icon."},"workspace_icon_color":{"type":"string","description":"The color of the workspace icon."},"create_time":{"type":"string","format":"date-time","description":"The timestamp when the workspace was created.","readOnly":true},"update_time":{"type":"string","format":"date-time","description":"The timestamp when the workspace was last updated.","readOnly":true},"creator_display_name":{"type":"string","description":"The display name of the user who created the workspace.","readOnly":true},"creator_email":{"type":"string","description":"The email address of the user who created the workspace.","readOnly":true},"organization_display_name":{"type":"string","description":"The display name of the parent organization, surfaced output-only to avoid\na second GetOrganization round-trip from clients that render the workspace's\nparent on the workspace settings page.","readOnly":true},"icon_data_uri":{"type":"string","description":"The workspace icon as a data URI following RFC 2397 (custom image upload).\nFormat: data:[<mediatype>][;encoding],<data>\nServer-side max payload size: 10MB.\n\nCoexists with `workspace_icon` (preset id) + `workspace_icon_color`. If both\n`icon_data_uri` and `workspace_icon` are set on update, the custom image wins."},"workspace_type":{"$ref":"#/components/schemas/v1WorkspaceType"}},"description":"A Workspace is a container for agents within an organization.","required":["title"]},"v1WorkspaceType":{"type":"string","enum":["WORKSPACE_TYPE_UNSPECIFIED","WORKSPACE_TYPE_FINANCE","WORKSPACE_TYPE_REGULAR"],"default":"WORKSPACE_TYPE_UNSPECIFIED","description":"The category/type of a workspace, used to tailor workspace behavior.\n\nDeliberately kept in its own file with no imports. `WorkspaceType` is needed\nby both `types.proto` (on `Workspace`) and `rbac.proto` (on `RoleTemplate`),\nand `types.proto` already imports `rbac.proto` for `RoleScope` — so defining\nit in either of those files makes the other's import cyclic.\n\n - WORKSPACE_TYPE_UNSPECIFIED: Not set. Not a workspace category in its own right: a workspace created\nwithout an explicit type is treated as WORKSPACE_TYPE_REGULAR, and this\nvalue is not a valid member of `RoleTemplate.workspace_types`.\n - WORKSPACE_TYPE_FINANCE: Finance workspace.\n - WORKSPACE_TYPE_REGULAR: Regular (general-purpose, automation-oriented) workspace — the default\nfor workspaces created without an explicit type.\n\nNumbered after FINANCE only because renumbering an existing value is a\nwire break; REGULAR is the baseline kind, not a later addition."},"v1UserWorkspaceMembership":{"type":"object","properties":{"workspace":{"type":"string","title":"Resource name of the workspace this membership refers to.\nFormat: organizations/{organization}/workspaces/{workspace}"},"your_roles":{"type":"array","items":{"$ref":"#/components/schemas/v1RoleBasicInfo"},"description":"The current user's role assignments scoped to this workspace.\nEmpty if the user only has org-level access (no direct workspace role)."},"joined_time":{"type":"string","format":"date-time","description":"The timestamp the user joined this workspace — the earliest\n`user_roles.created_at` for any of their roles in this workspace. Unset if\nthe user has no direct workspace-level role assignment."}},"description":"Per-workspace membership context for the current user, returned alongside\n`Workspace` in `CurrentUserOrganizationWorkspacesResponse.memberships`.","required":["workspace"]},"v1RoleBasicInfo":{"type":"object","properties":{"name":{"type":"string","description":"The role name (e.g., \"workspace-admin\", \"org-admin\", or custom role name)."},"role_scope":{"$ref":"#/components/schemas/v1RoleScope"}},"title":"Lightweight role information following the UserBasicInfo pattern.\nNote: RoleScope is imported from rbac.proto"},"v1RoleScope":{"type":"string","enum":["ROLE_SCOPE_UNSPECIFIED","ROLE_SCOPE_ORGANIZATION","ROLE_SCOPE_WORKSPACE"],"default":"ROLE_SCOPE_UNSPECIFIED","description":"Defines the scope at which a role can be applied.\n\n - ROLE_SCOPE_UNSPECIFIED: Unspecified role scope.\n - ROLE_SCOPE_ORGANIZATION: Role applies at the organization level.\n - ROLE_SCOPE_WORKSPACE: Role applies at the workspace level."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/me/organizations/{organization_id}/workspaces":{"get":{"summary":"Current User Organization Workspaces","operationId":"CurrentUserOrganizationWorkspaces","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1CurrentUserOrganizationWorkspacesResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page_size","description":"The maximum number of workspaces to return.\nIf unspecified, at most 50 workspaces will be returned.\nThe maximum value is 1000; values above 1000 will be coerced to 1000.","in":"query","required":false,"schema":{"type":"integer","format":"int64"}},{"name":"page_token","description":"A page token, received from a previous `CurrentUserOrganizationWorkspaces` call.\nProvide this to retrieve the subsequent page.\nWhen paginating, all other parameters provided to `CurrentUserOrganizationWorkspaces` must match\nthe call that provided the page token.","in":"query","required":false,"schema":{"type":"string"}},{"name":"filter","description":"Optional filter string following AIP-160 filtering standards.\nExample: \"title='Development'\"","in":"query","required":false,"schema":{"type":"string"}},{"name":"order_by","description":"Optional comma-separated list of fields to order by, following AIP-132.\nSupported fields: title, create_time, update_time\nExample: \"title\", \"create_time desc\", \"update_time desc,title\"\nDefault ordering is by title ascending (alphabetical) if not specified.","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Workspaces"]}}}}
```

## Current User Workspace Roles

> Returns the current authenticated user's roles in a workspace.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Workspaces","description":"Manage workspaces, members, roles, invitations, and preferences."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1CurrentUserWorkspaceRolesResponse":{"type":"object","properties":{"roles":{"type":"array","items":{"$ref":"#/components/schemas/v1Role"},"description":"List of roles the current user has in the workspace."}},"description":"Response message for CurrentUserWorkspaceRoles."},"v1Role":{"type":"object","properties":{"name":{"type":"string","title":"Resource name of the role.\nFormat: organizations/{organization}/roles/{role} (org-level)\nFormat: organizations/{organization}/workspaces/{workspace}/roles/{role} (workspace-level)","description":"List responses also use this message for entries that are not concrete\nrole instances, in which case `name` carries the referenced resource:\n  roleTemplates/{role_template} for system-defined templates\n  organizations/{organization}/workspaces/{workspace}/customRoles/{custom_role}\n    for workspace custom roles, which additionally set `custom`.\nThese are not declared as patterns above because AIP-123 requires every\npattern's final segment to contain this resource's own singular."},"title":{"type":"string","description":"Human-readable title of the role (e.g., \"Administrator\", \"Editor\")."},"description":{"type":"string","description":"Description of what this role grants."},"permissions":{"type":"array","items":{"type":"string"},"title":"List of permission strings this role grants.\nFormat: \"{action}:{resource_path}\" (e.g., \"GET:/api/v1/me\")","readOnly":true,"description":"Superseded by `permission_details`, which carries these same strings plus\ntheir display metadata; this field is slated for removal in the next major\nversion. It is not yet marked `deprecated` because clients cannot migrate\nuntil Agora populates `permission_details` — do that first, then flip the\noption, then remove the field."},"permission_description":{"type":"string","description":"Description of the permissions granted by this role."},"custom":{"type":"boolean","description":"True when this entry is a workspace-scoped custom role rather than a\nsystem-defined role template. Lets clients tell the two apart without\nparsing `name`."},"permission_details":{"type":"array","items":{"$ref":"#/components/schemas/v1RolePermission"},"description":"The permissions this role grants, with the display metadata needed to render\nthem. Supersedes `permissions`, which carries the same strings without it.\n\n`RolePermission.permission` is self-sufficient — it is the same\n\"{action}:{resource_path}\" string — so a client needs only this field.\n\nKeyed by the permission string rather than positional: entries correspond to\n`permissions` by `RolePermission.permission`, not by index. An entry may be\nabsent when a permission has no backing template metadata, so a client must\nfall back to the raw `permissions` string rather than assume coverage.","readOnly":true}},"description":"A Role represents a concrete, assignable role that can be assigned to users.\nRoles can be created from RoleTemplates or as standalone custom roles.","required":["title"]},"v1RolePermission":{"type":"object","properties":{"permission":{"type":"string","title":"The permission this describes, matching an entry in `Role.permissions`.\nFormat: \"{action}:{resource_path}\" (e.g., \"GET:/api/v1/me\")"},"display_name":{"type":"string","description":"Human-readable name of the permission (e.g., \"me:read\").\nMirrors the permission template's display name."},"description":{"type":"string","description":"What this permission allows. May be empty; not every template sets one."}},"description":"Display metadata for one permission a role grants.\n\nCarries only the human-readable name and description: the action and resource\npath are already encoded in the `Role.permissions` string this joins to, so\nrepeating them would double the payload of the field it describes for no gain."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/me/organizations/{organization_id}/workspaces/{workspace_id}/roles":{"get":{"summary":"Current User Workspace Roles","description":"Returns the current authenticated user's roles in a workspace.","operationId":"CurrentUserWorkspaceRoles","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1CurrentUserWorkspaceRolesResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Workspaces"]}}}}
```

## List Workspace Permissions

> Lists the permissions that can be granted within a workspace.\
> \
> The client-facing counterpart to the internal ListPermissionTemplates: it\
> returns the same catalog with its display metadata, but omits the\
> PAT-allow-list fields (\`pat\_eligible\`, the global schema version) so it\
> cannot be mistaken for an authorization input.\
> \
> Only workspace-scoped permissions are returned, so every entry is valid\
> input to CreateCustomRole — a client never has to re-implement the\
> scope rule to avoid offering a choice the server rejects.\
> \
> The result IS narrowed by the workspace's type: a permission declares which\
> WorkspaceTypes it applies to, and one that does not apply here is not\
> offered. A permission declaring none is UNCLASSIFIED and treated as\
> WORKSPACE\_TYPE\_REGULAR, so finance-style workspaces must opt in explicitly.\
> \
> That makes this list a strict SUBSET of what CreateCustomRole accepts, not a\
> mirror of it: the validator checks workspace-scoping only, so it still\
> accepts a permission this endpoint hides. The direction that matters is\
> preserved — everything offered is accepted, so the picker never presents a\
> choice the server rejects — but do not infer the converse. Hiding a\
> permission here does NOT prevent it being granted, and does not stop an\
> already-granted one from authorizing.\
> \
> The result is NOT narrowed to permissions the caller themselves holds. An\
> admin can therefore compose a role stronger than their own. If that should\
> change, it changes in the validator first and here second.\
> \
> Returns the complete set in one response; see the paging fields on\
> ListWorkspacePermissionsRequest.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Workspaces","description":"Manage workspaces, members, roles, invitations, and preferences."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ListWorkspacePermissionsResponse":{"type":"object","properties":{"permissions":{"type":"array","items":{"$ref":"#/components/schemas/v1Permission"},"description":"The permissions that can be granted in the workspace."},"next_page_token":{"type":"string","description":"A token to retrieve the next page of results.\n\nAlways empty today: the full set is returned in one response. Present so\npaging can be introduced without a contract change."}},"description":"Response message for ListWorkspacePermissions."},"v1Permission":{"type":"object","properties":{"name":{"type":"string","description":"This is the value to pass in CustomRole.permission_templates to grant it.","title":"Reference to the permission template this permission comes from.\nFormat: permissionTemplates/{permission_template}"},"title":{"type":"string","description":"Human-readable title of the permission (e.g., \"automation:read\").\nMirrors the permission template's display name."},"description":{"type":"string","description":"What this permission allows. May be empty; not every template sets one."},"action":{"type":"string","description":"The HTTP verb this permission covers: \"GET\", \"POST\", \"PATCH\", \"PUT\" or\n\"DELETE\".\n\nThe raw verb as stored on the template, NOT the CRUD `Action` enum: that\nenum collapses PATCH and PUT into ACTION_UPDATE, and a client cannot\nreconstruct which one a `Role.permissions` entry refers to. Clients also\nuse this to group permissions as read (GET) versus write."},"resource_path":{"type":"string","description":"The resource path pattern this permission applies to, with placeholders\n(e.g., \"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}\").\n\n`action` and `resource_path` composed as \"{action}:{resource_path}\" give\nthe exact strings Role.permissions and CustomRole.permissions carry, which\nis how a client joins a role's permissions to their display metadata."},"category":{"type":"string","description":"Grouping key for presenting this permission under a feature heading, e.g.\n\"build-and-fleet\". Mirrors PermissionTemplate.category.\n\nA KEY, not a display label: clients own the key-to-label mapping, so a\nsection can be renamed, reordered or translated without a chart change in\nevery service that ships permissions under it.\n\nEmpty means UNCLASSIFIED, and clients should group those under a heading of\ntheir own choosing (\"Other\") rather than hiding them. An uncategorised\npermission is still perfectly grantable, and a visibly large Other section\nis what prompts someone to classify it — hiding them makes the omission\ninvisible instead.\n\nCarried here specifically so a role builder can group the list in ONE call.\nWithout it the only source is ListPermissionTemplates, forcing a second\nrequest and a join on permissionTemplates/{id}."}},"description":"A Permission is a single grantable permission, as presented to clients.\n\nA projection of a PermissionTemplate carrying only what a client needs to\ndisplay it and to grant it. It deliberately omits `pat_eligible`: that field\nis a PAT revocation mechanism gated on the global schema version, and mixing\nit into a display payload would invite clients to cache it without the\nversion (see AGENTS.md, \"Global schema version and the authorization\nsnapshot\")."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/permissions":{"get":{"summary":"List Workspace Permissions","description":"Lists the permissions that can be granted within a workspace.\n\nThe client-facing counterpart to the internal ListPermissionTemplates: it\nreturns the same catalog with its display metadata, but omits the\nPAT-allow-list fields (`pat_eligible`, the global schema version) so it\ncannot be mistaken for an authorization input.\n\nOnly workspace-scoped permissions are returned, so every entry is valid\ninput to CreateCustomRole — a client never has to re-implement the\nscope rule to avoid offering a choice the server rejects.\n\nThe result IS narrowed by the workspace's type: a permission declares which\nWorkspaceTypes it applies to, and one that does not apply here is not\noffered. A permission declaring none is UNCLASSIFIED and treated as\nWORKSPACE_TYPE_REGULAR, so finance-style workspaces must opt in explicitly.\n\nThat makes this list a strict SUBSET of what CreateCustomRole accepts, not a\nmirror of it: the validator checks workspace-scoping only, so it still\naccepts a permission this endpoint hides. The direction that matters is\npreserved — everything offered is accepted, so the picker never presents a\nchoice the server rejects — but do not infer the converse. Hiding a\npermission here does NOT prevent it being granted, and does not stop an\nalready-granted one from authorizing.\n\nThe result is NOT narrowed to permissions the caller themselves holds. An\nadmin can therefore compose a role stronger than their own. If that should\nchange, it changes in the validator first and here second.\n\nReturns the complete set in one response; see the paging fields on\nListWorkspacePermissionsRequest.","operationId":"ListWorkspacePermissions","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ListWorkspacePermissionsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page_size","description":"Accepted for forward compatibility and currently IGNORED: the full set is\nalways returned in a single response.\n\nBoth client uses — building a lookup map to label a role's permissions, and\npopulating a custom-role picker — need the whole catalog before they can\nrender anything, so paging would only force every caller into a fetch loop.\nThe catalog is a small, static, cacheable set. If it ever grows enough to\nneed paging, these fields are already in the contract.","in":"query","required":false,"schema":{"type":"integer","format":"int64"}},{"name":"page_token","description":"Accepted for forward compatibility and currently IGNORED. See page_size.","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Workspaces"]}}}}
```
