openapi: 3.2.0 info: title: Kognitos Workspaces API version: 1.0.0 contact: name: Kognitos url: https://kognitos.com license: name: MIT url: https://opensource.org/licenses/MIT description: 'Operations tagged Workspaces across 2 of this provider''s published API definitions: kognitos-openapi.yaml, kognitos-openapi.yml. Each path carries the servers of the definition it was published in.' servers: - url: https://app.us-1.kognitos.com security: - BearerAuth: [] tags: - name: Workspaces description: Manage workspaces, members, roles, invitations, and preferences. 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 servers: - url: https://app.us-1.kognitos.com /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. If unspecified, at most 50 invitations will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000.' in: query required: false schema: type: integer format: int32 - name: page_token description: 'A page token, received from a previous ListWorkspaceUserInvites call. Provide this to retrieve the subsequent page.' in: query required: false schema: type: string tags: - Workspaces servers: - url: https://app.us-1.kognitos.com /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. If unspecified, at most 50 roles will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000.' in: query required: false schema: type: integer format: int32 - name: page_token description: 'A page token, received from a previous ListWorkspaceRoles call. Provide this to retrieve the subsequent page.' in: query required: false schema: type: string tags: - Workspaces servers: - url: https://app.us-1.kognitos.com /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. If unspecified, at most 50 users will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000.' in: query required: false schema: type: integer format: int32 - name: page_token description: 'A page token, received from a previous `ListWorkspaceUsers` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `ListWorkspaceUsers` must match the call that provided the page token.' in: query required: false schema: type: string - name: filter description: 'Optional filter string following AIP-160 filtering standards. Supported filter fields: - `role`: Filter by role name (case-insensitive). Example: `role="Workspace Viewer"` - `role_scope`: Filter by role scope. Values: "organization" or "workspace". Example: `role_scope=workspace` - `search`: Search by user display name or email (partial match). Example: `search:"john"`' in: query required: false schema: type: string - name: order_by description: 'Optional comma-separated list of fields to order by, following AIP-132. Supported fields: display_name, email, created_time, updated_time Example: "display_name,created_time desc" Default ordering is by created_time descending if not specified.' in: query required: false schema: type: string tags: - Workspaces servers: - url: https://app.us-1.kognitos.com /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 servers: - url: https://app.us-1.kognitos.com /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 servers: - url: https://app.us-1.kognitos.com /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. If unspecified, at most 50 workspaces will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000.' in: query required: false schema: type: integer format: int32 - name: page_token description: 'A page token, received from a previous `ListWorkspaces` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `ListWorkspaces` must match the 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. Supported fields: title, create_time, update_time Example: "title", "create_time desc", "update_time desc,title" Default ordering is by create_time descending if not specified.' in: query required: false schema: type: string tags: - Workspaces servers: - url: https://app.us-1.kognitos.com /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. If unspecified, at most 50 workspaces will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000.' in: query required: false schema: type: integer format: int32 - name: page_token description: 'A page token, received from a previous `CurrentUserOrganizationWorkspaces` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `CurrentUserOrganizationWorkspaces` must match the call that provided the page token.' in: query required: false schema: type: string - name: filter description: 'Optional filter string following AIP-160 filtering standards. Example: "title=''Development''"' in: query required: false schema: type: string tags: - Workspaces servers: - url: https://app.us-1.kognitos.com components: schemas: v1UserWithRoles: type: object properties: user: $ref: '#/components/schemas/v1UserBasicInfo' roles: type: array items: $ref: '#/components/schemas/v1RoleBasicInfo' description: 'The user''s assigned roles. Each role includes its scope (organization or workspace).' description: 'A user with their assigned roles. This type is reusable for both organization and workspace user listing APIs. The RoleScope field in each role indicates whether the role is org-level or workspace-level.' 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. Pass this value in the `page_token` field in the subsequent call to `CurrentUserOrganizationWorkspaces` to get the next page of results. If this field is empty, it means there are no more results.' description: Response message for listing workspaces for the current user within a specific organization. rpcStatus: type: object properties: code: type: integer format: int32 message: type: string details: type: array items: $ref: '#/components/schemas/protobufAny' CountWorkspaceUsersBody: type: object properties: workspace_ids: type: array items: type: string title: 'The list of workspace IDs to get user counts for. Each workspace_id should be the workspace identifier (not the full resource name). The full workspace resource names will be constructed as: organizations/{organization}/workspaces/{workspace_id}' description: Request message for counting users in specific workspaces. required: - workspace_ids 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." 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. Note: RoleScope is imported from rbac.proto' protobufAny: type: object properties: '@type': type: string additionalProperties: {} 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. The 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. 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. Pass this value in the page_token field in the subsequent call to ListWorkspaceUserInvites to get the next page of results.' description: Response message for ListWorkspaceUserInvites. 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)." v1ListWorkspaceRolesResponse: type: object properties: roles: type: array items: $ref: '#/components/schemas/v1Role' description: The list of roles in the workspace. next_page_token: type: string description: 'A token to retrieve the next page of results. Pass this value in the page_token field in the subsequent call to ListWorkspaceRoles to get the next page of results.' description: Response message for ListWorkspaceRoles. 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. Pass this value in the `page_token` field in the subsequent call to `ListWorkspaceUsers` to get the next page of results. If this field is empty, it means there are no more results.' description: Response message for listing users in a workspace. 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)." v1WorkspacePreferences: type: object properties: name: type: string title: 'The resource name of the workspace preferences. Format: `organizations/{organization}/workspaces/{workspace}/preferences`' support_team_access: type: boolean description: Support team access to workspace for debugging issues. general: $ref: '#/components/schemas/v1GeneralPreferences' description: Represents workspace-specific settings or preferences. 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." v1UserInvitation: type: object properties: email: type: string description: The user's email address. invitation_id: type: string description: The invitation ID. description: A UserInvitation represents a pending invitation with user email and invitation ID. v1UserBasicInfo: type: object properties: name: type: string title: 'The unique resource name of the user basic info. Format: `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. description: 'Contains basic information about a user. This is a lightweight representation used when full user details are not needed.' v1Workspace: type: object properties: name: type: string description: 'The resource name of the workspace. Format: organizations/{organization}/workspaces/{workspace} This field is assigned by the server at creation and is immutable thereafter. Clients 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. This corresponds to the `name` column in the database.' workspace_icon: type: string description: 'The workspace icon data. This 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 description: A Workspace is a container for agents within an organization. required: - title v1Role: type: object properties: name: type: string title: 'Resource name of the role. Format: organizations/{organization}/roles/{role} (org-level) Format: organizations/{organization}/workspaces/{workspace}/roles/{role} (workspace-level)' 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. Format: "action:Resource" (e.g., "create:Automation", "read:Workspace")' readOnly: true description: 'A Role represents a concrete, assignable role that can be assigned to users. Roles can be created from RoleTemplates or as standalone custom roles.' required: - title 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. Pass this value in the `page_token` field in the subsequent call to `ListWorkspaces` to get the next page of results. If this field is empty, it means there are no more results.' description: Response message for listing workspaces. v1GeneralPreferences: type: object properties: time_zone: type: string description: 'The time zone preference. Should 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. measurement_system: $ref: '#/components/schemas/v1MeasurementSystem' description: 'General preferences for display and formatting. Used by both workspace and organization preferences.' 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." securitySchemes: BearerAuth: type: http scheme: bearer description: Personal Access Token. x-refined-from: - kognitos-openapi.yaml - kognitos-openapi.yml