Kognitos Workspaces API

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