openapi: 3.0.0 info: title: Kognitos API description: REST API for Kognitos platform — PAT-eligible endpoints version: 1.0.0 contact: name: Kognitos url: https://kognitos.com license: name: MIT url: https://opensource.org/licenses/MIT tags: - name: Organizations description: Manage organizations, users, roles, invitations, and preferences. - name: Workspaces description: Manage workspaces, members, roles, invitations, and preferences. - name: Automations description: Create and configure automations, revisions, schedules, triggers, and connections. - name: Runs description: Execute automations and manage run lifecycle — start, pause, continue, and view events. - name: Books description: Browse and search books, concepts, procedures, connections, and triggers. - name: Files description: Upload, download, and manage files. - name: Exceptions description: Track exceptions, view analytics, manage agent events, and access troubleshooting guides. - name: Analytics description: Query dashboards, automation estimates, insights, and metrics. - name: Agents description: Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books. - name: Secrets description: Manage secrets, secret backends, OAuth apps and secret types. - name: Assets description: "Manage workspace assets: upload, organise, duplicate, move and download." - name: Folders description: Organise assets into folders. - name: Collections description: Manage collections, their schemas and rows. - name: Work Items description: Track work items and work units that need human input. - name: Guides description: Manage workspace guides that steer exception handling. - name: Audit Events description: Read and export the organization audit log. security: - BearerAuth: [] paths: "/api/v1/organizations/{organization_id}": get: summary: Get Organization operationId: GetOrganization responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Organization" 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 tags: - Organizations /api/v1/me/organizations: get: summary: Current User Organizations operationId: CurrentUserOrganizations responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1CurrentUserOrganizationsResponse" default: description: An unexpected error response. content: application/json: schema: $ref: "#/components/schemas/rpcStatus" parameters: - name: page_size description: >- The maximum number of organizations to return. If unspecified, at most 50 organizations will be returned. The 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 `ListCurrentUserOrganizations` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `ListCurrentUserOrganizations` 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='My Organization'" 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 title ascending (alphabetical) if not specified. in: query required: false schema: type: string tags: - Organizations "/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 "/api/v1/organizations/{organization_id}/preferences": get: summary: Get Organization Preferences operationId: GetOrganizationPreferences responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1OrganizationPreferences" 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 tags: - Organizations "/api/v1/organizations/{organization_id}/invitations/{invitation_id}": get: summary: Get Invitation operationId: GetInvitation responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Invitation" 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: invitation_id in: path required: true schema: type: string tags: - Organizations "/api/v1/organizations/{organization_id}/invites": get: summary: List Organization User Invites operationId: ListOrganizationUserInvites responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ListOrganizationUserInvitesResponse" 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 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: int64 - name: page_token description: >- A page token, received from a previous ListOrganizationUserInvites call. Provide this to retrieve the subsequent page. in: query required: false schema: type: string - name: direction description: |- Optional filter by direction. Defaults to `INVITE`. Pass `REQUEST` to surface pending user-initiated access requests in the admin UI as a separate tab. - INVITATION_DIRECTION_UNSPECIFIED: Unspecified — treated as INVITE for backward compatibility. - INVITATION_DIRECTION_INVITE: Admin invites a user to join an org or workspace. (Default; pre-existing behavior.) - INVITATION_DIRECTION_REQUEST: User requests access to an org or workspace they can't currently reach (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: - Organizations "/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: int64 - 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 - name: direction description: |- Optional filter by direction. Defaults to `INVITE`. - INVITATION_DIRECTION_UNSPECIFIED: Unspecified — treated as INVITE for backward compatibility. - INVITATION_DIRECTION_INVITE: Admin invites a user to join an org or workspace. (Default; pre-existing behavior.) - INVITATION_DIRECTION_REQUEST: User requests access to an org or workspace they can't currently reach (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 "/api/v1/organizations/{organization_id}/roles": get: summary: List Organization Roles operationId: ListOrganizationRoles responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ListOrganizationRolesResponse" 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 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: int64 - name: page_token description: |- A page token, received from a previous ListOrganizationRoles call. Provide this to retrieve the subsequent page. in: query required: false schema: type: string tags: - Organizations "/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: int64 - 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 "/api/v1/organizations/{organization_id}/users": get: summary: List Organization Users operationId: ListOrganizationUsers responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ListOrganizationUsersResponse" 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 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: int64 - name: page_token description: >- A page token, received from a previous `ListOrganizationUsers` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `ListOrganizationUsers` 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: - `display_name`: Filter by display name (case-insensitive partial match). Example: `display_name:"john"` - `email`: Filter by email address (case-insensitive partial match). Example: `email:"kognitos.com"` - `role`: Filter by role name (exact match, case-insensitive). Example: `role="Organization Admin"` - `role_scope`: Filter by role scope. Values: "organization" or "workspace". Example: `role_scope=organization` - `last_active_time`: Filter by last-active timestamp range using `>=`, `>`, `<=` or `<` against an RFC3339 timestamp. Example: `last_active_time >= "2026-07-01T00:00:00Z"` Users with no last-active value are excluded by any range bound. Filters 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. Supported fields: display_name, email, created_time, updated_time, last_active_time Example: "display_name asc", "created_time desc" Default ordering is by created_time descending if not specified. Users with no `last_active_time` sort as least-recently-active: last under `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. Defaults to false. Returned rows will have `User.state = USER_STATE_DEACTIVATED`. in: query required: false schema: type: boolean tags: - Organizations "/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: int64 - 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: - `display_name`: Filter by display name (case-insensitive partial match). Example: `display_name:"john"` - `email`: Filter by email address (case-insensitive partial match). Example: `email:"kognitos.com"` - `role`: Filter by role name (exact match, case-insensitive). Example: `role="Workspace Viewer"` - `role_scope`: Filter by role scope. Values: "organization" or "workspace". Example: `role_scope=workspace` - `last_active_time`: Filter by last-active timestamp range using `>=`, `>`, `<=` or `<` against an RFC3339 timestamp. Example: `last_active_time >= "2026-07-01T00:00:00Z"` Users with no last-active value are excluded by any range bound. Filters 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. Supported fields: display_name, email, created_time, updated_time, last_active_time Example: "display_name,created_time desc" Default ordering is by created_time descending if not specified. Users with no `last_active_time` sort as least-recently-active: last under `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. Defaults to false. Returned rows will have `User.state = USER_STATE_DEACTIVATED`. in: query required: false schema: type: boolean tags: - Workspaces "/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 "/api/v1/organizations/{organization_id}/users/{user_id}": get: summary: Get User Basic Info operationId: GetUserBasicInfo responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1UserBasicInfo" 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: user_id in: path required: true schema: type: string tags: - Organizations "/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 "/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: int64 - 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. The expression follows the syntax defined in AIP-160. Supported fields for filtering: - `title`: The display name of the workspace Examples: - `title = "My Workspace"` - exact match - `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 "/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: int64 - 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 - 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 title ascending (alphabetical) if not specified. in: query required: false schema: type: string tags: - Workspaces "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}": get: summary: Get Automation operationId: GetAutomation responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Automation" 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: automation_id in: path required: true schema: type: string - name: show_deleted description: |- If true, the request will return the automation even if it has been soft-deleted. Deleted automations will have the `delete_time` field populated. in: query required: false schema: type: boolean tags: - Automations patch: summary: Update Automation description: UpdateAutomation modifies an existing automation with new code, artifacts, or dependencies. operationId: UpdateAutomation responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Automation" 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: automation_id in: path required: true schema: type: string - name: update_mask description: |- For partial updates: If specified, only fields specified in the field mask are updated. Otherwise, all fields are updated. Fields are relative to the Automation message. in: query required: false schema: type: string requestBody: content: application/json: schema: type: object properties: display_name: type: string description: |- Human-readable name of the automation for identification and display. Must be unique within the user's namespace. english_code: type: string description: |- User-facing English description code that explains what the automation does. This is a human-readable representation of the automation's purpose and logic. code: type: string description: |- SPy (Subset-of Python) executable code that defines the automation logic. This code is executed when the automation is invoked with inputs. artifacts: type: object additionalProperties: type: string format: byte description: |- Additional artifacts associated with the automation (e.g., data files, configurations). Keys are artifact names, values are the binary content of the artifacts. These artifacts are available to the automation during execution. code_manifest: $ref: "#/components/schemas/v1CodeManifest" create_time: type: string format: date-time description: |- Timestamp when the automation was originally created. This value never changes after creation. readOnly: true version: type: string title: |- Semantic version of this specific version of the automation (format: major.minor). Incremented each time the automation is updated or published. Examples: "0.1", "1.0", "1.1", "2.0" readOnly: true connections: type: object additionalProperties: $ref: "#/components/schemas/v1BookConnection" description: |- Book connections required by this automation for execution. Maps connection names to their metadata. These connections are resolved and made available during automation execution. collections: type: object additionalProperties: $ref: "#/components/schemas/v1CollectionRef" description: |- Collections required by this automation, resolved to concrete references. Maps each collection slug to its CollectionRef (mirrors connections). config: type: object additionalProperties: $ref: "#/components/schemas/v1ConfigValue" description: |- Business-tunable configuration values for this automation, keyed by config name. Each ConfigValue holds the value plus a human-readable editor label. Set at build time, edited by the user to tune behavior, read in SPy as kognitos.config.. update_time: type: string format: date-time description: |- Timestamp when the automation was last updated. Updated whenever the automation metadata, code, or dependencies change. readOnly: true update_user_id: type: string description: The ID of the user who last updated this automation. readOnly: true delete_time: type: string format: date-time description: Timestamp when the automation was deleted. readOnly: true purge_time: type: string format: date-time description: Timestamp when the automation will be purged. readOnly: true input_specs: type: array items: $ref: "#/components/schemas/v1AutomationInputSpec" description: |- List of input specifications that define the parameters this automation accepts. These specifications describe the expected inputs when the automation is executed. description: type: string description: Provides additional context and documentation about the automation's purpose and behavior. latest_published_version: type: string title: |- Semantic version of the latest published version of the automation (format: major.minor). It will be null in case of no published version. Examples: "0.1", "1.0", "2.0" readOnly: true author_id: type: string description: The ID of the user who created this automation. readOnly: true code_mapping: $ref: "#/components/schemas/v1CodeMapping" source_map: $ref: "#/components/schemas/v1SourceMap" restore_time: type: string format: date-time description: |- Timestamp when the automation was restored from a previous version. Only populated if the automation has been restored. readOnly: true restore_version: type: string description: |- The version string this automation was restored from (e.g., "1.0", "2.1"). Only populated if the automation has been restored. readOnly: true restore_user_id: type: string description: |- The ID of the user who restored this automation. Only populated if the automation has been restored. readOnly: true publish_time: type: string format: date-time description: |- Timestamp when the automation was last published. Only populated if the automation has been published. readOnly: true publish_user_id: type: string description: |- The ID of the user who last published this automation. Only populated if the automation has been published. readOnly: true activation_state: $ref: "#/components/schemas/v1AutomationActivationState" default_inputs: type: object additionalProperties: $ref: "#/components/schemas/commonv1Value" description: |- Default input values for this automation. Keys are input parameter names (matching AutomationInputSpec.name), values are the default values to use when inputs are not explicitly provided. These are used to pre-populate inputs for manual runs and fill missing inputs for trigger-based invocations. readOnly: true marked_outputs: type: array items: type: string description: |- List of output keys that have been marked by the user. These keys identify specific outputs from the automation execution. code_length: type: integer format: int32 description: The length in characters of the SPy (Subset-of-Python) code. readOnly: true kind: $ref: "#/components/schemas/v1AutomationKind" labels: type: array items: type: string description: |- User-defined labels on the automation, e.g. "finance", "AP". Labels belong to the automation, not to a version: changing them does not create a new version. Ordered case-insensitively. Managed via SetAutomationLabels. readOnly: true title: Automation to update and new values for the automation. required: - display_name description: Automation to update and new values for the automation. required: true tags: - Automations delete: summary: Delete Automation description: |- DeleteAutomation soft deletes an automation from the system. The automation is purged sometime after it has been deleted. operationId: DeleteAutomation responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Automation" 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: automation_id in: path required: true schema: type: string - name: force description: |- If set to true, any child resources (such as revisions) will also be deleted. If set to false and the automation has child resources, the delete will fail. Per AIP-135, this field is required for resources with children. in: query required: false schema: type: boolean tags: - Automations "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:query": get: summary: Query Automation description: >- This custom method allows explicit selection of which version stage to retrieve: - AUTOMATION_STAGE_DRAFT: Returns the latest draft version - AUTOMATION_STAGE_PUBLISHED: Returns the latest published version operationId: QueryAutomation responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Automation" 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: automation_id in: path required: true schema: type: string - name: stage description: >- The publication stage of the automation to retrieve. Determines which version of the automation to return: - AUTOMATION_STAGE_DRAFT: Returns the latest draft version - AUTOMATION_STAGE_PUBLISHED: Returns the latest published version - AUTOMATION_STAGE_UNSPECIFIED: Automation stage is not specified. - AUTOMATION_STAGE_DRAFT: Automation is in draft stage and can be modified. - AUTOMATION_STAGE_PUBLISHED: Automation is published and immutable, ready for execution. in: query required: true schema: type: string enum: - AUTOMATION_STAGE_UNSPECIFIED - AUTOMATION_STAGE_DRAFT - AUTOMATION_STAGE_PUBLISHED default: AUTOMATION_STAGE_UNSPECIFIED tags: - Automations "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/revisions/{revision_id}": get: summary: Get Automation Revision operationId: GetAutomationRevision responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1AutomationRevision" 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: automation_id in: path required: true schema: type: string - name: revision_id in: path required: true schema: type: string tags: - Automations "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/revisions": get: summary: List Automation Revisions operationId: ListAutomationRevisions responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ListAutomationRevisionsResponse" 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: automation_id in: path required: true schema: type: string - name: page_size description: >- The maximum number of revisions to return in a single response. The service may return fewer than this value. If unspecified, at most 50 revisions 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 `ListAutomationRevisions` call. Provide this to retrieve the subsequent page of results. in: query required: false schema: type: string - name: filter description: >- Filter expression to restrict results. Per AIP-160, this should be a filtering expression following the Common Expression Language (CEL) syntax. Supported fields for filtering: - `stage`: The automation revision stage (e.g., DRAFT, PUBLISHED) Example filters: - `stage = "DRAFT"` - Returns only draft revisions - `stage = "PUBLISHED"` - Returns only published revisions If not specified or passed null, all revisions will be returned for that automation. in: query required: false schema: type: string tags: - Automations "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations": get: summary: List Automations operationId: ListAutomations responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ListAutomationsResponse" 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 automations to return in a single response. The service may return fewer than this value. If unspecified, at most 10 automations will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. If negative, an INVALID_ARGUMENT error will be returned. in: query required: false schema: type: integer format: int32 - name: page_token description: >- A page token received from a previous `ListAutomations` call. Provide this to retrieve the subsequent page of results. When paginating, all other parameters provided to `ListAutomations` must match the call that provided the page token. in: query required: false schema: type: string - name: show_deleted description: Filter to show/hide deleted automations. Deleted automations will be hidden by default. in: query required: false schema: type: boolean - name: filter description: |- Filter expression to restrict results. Per AIP-160, this should be a filtering expression following the Common Expression Language (CEL) syntax. Supported fields for filtering: - `state`: The automation state (e.g., DRAFT, PUBLISHED) - `labels`: Automations carrying the label (case-insensitive match) Example filters: - `state = "PUBLISHED"` - `labels:"finance"` - `labels:"finance" OR labels:"ap"` (carries any of the labels) - `labels:"finance" AND labels:"ap"` (carries all of the labels) in: query required: false schema: type: string - name: order_by description: >- Reserved for future use. Comma-separated list of fields to order results by. Per AIP-132, this should be a string containing one or more field names, each optionally followed by "asc" or "desc" to specify sort direction. Currently not implemented. Results are always ordered by `update_time desc` (most recently updated first). in: query required: false schema: type: string tags: - Automations post: summary: Create Automation description: |- CreateAutomation creates a new automation with the provided name, code, and dependencies. The created automation will have type DRAFT and can be updated before being published. Returns the created automation with a unique ID and metadata. operationId: CreateAutomation responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Automation" 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 requestBody: content: application/json: schema: $ref: "#/components/schemas/v1Automation" description: The automation to create required: true tags: - Automations "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:invoke": post: summary: Invoke Automation operationId: InvokeAutomation responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1InvokeAutomationResponse" 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: automation_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/InvokeAutomationBody" required: true tags: - Automations "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:listDefaultInputsHistory": get: summary: List Default Inputs History description: |- Results are returned in reverse chronological order (newest first). Optionally filter by stage (DRAFT or PUBLISHED). operationId: ListDefaultInputsHistory responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ListDefaultInputsHistoryResponse" 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: automation_id in: path required: true schema: type: string - name: page_size description: Maximum number of entries to return. Defaults to 50 if not specified. in: query required: false schema: type: integer format: int32 - name: page_token description: Page token for pagination, from a previous ListDefaultInputsHistoryResponse. in: query required: false schema: type: string tags: - Automations "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations:countConnectionUsage": post: summary: Count Connection Usage operationId: CountConnectionUsage responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1CountConnectionUsageResponse" 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 requestBody: content: application/json: schema: $ref: "#/components/schemas/CountConnectionUsageBody" required: true tags: - Automations "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations:traceConnectionUsage": post: summary: Trace Connection Usage operationId: TraceConnectionUsage responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1TraceConnectionUsageResponse" 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 requestBody: content: application/json: schema: $ref: "#/components/schemas/TraceConnectionUsageBody" required: true tags: - Automations "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:extractCodeConnections": get: summary: Extract Automation Code Connections operationId: ExtractAutomationCodeConnections responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ExtractAutomationCodeConnectionsResponse" 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: automation_id in: path required: true schema: type: string - name: filter description: >- Filter expression to restrict results. Per AIP-160, this should be a filtering expression following the Common Expression Language (CEL) syntax. Supported fields for filtering: - `stage`: The automation stage to extract connections from (e.g., DRAFT, PUBLISHED) Example filters: - `stage = "DRAFT"` - `stage = "PUBLISHED"` in: query required: true schema: type: string tags: - Automations "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:upgradeConnections": post: summary: Upgrade Automation Connections description: >- Multiple connections can be upgraded in a single atomic operation. All upgrades succeed together or all fail together. The automation version is incremented once for all upgrades. This operation only works on draft automations. To upgrade connections in a published automation, first use ForkPublishedAutomation to create a draft, then call this method. Per AIP-136, this is a custom method using the :upgradeConnections suffix. operationId: UpgradeAutomationConnections responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1UpgradeAutomationConnectionsResponse" 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: automation_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/UpgradeAutomationConnectionsBody" required: true tags: - Automations "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:switchConnections": post: summary: Switch Automation Connections description: >- Multiple connections can be switched in a single atomic operation. All switches succeed together or all fail together. The automation version is incremented once for all switches. This operation only works on draft automations. To switch connections in a published automation, first use ForkPublishedAutomation to create a draft, then call this method. Per AIP-136, this is a custom method using the :switchConnections suffix. operationId: SwitchAutomationConnections responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1SwitchAutomationConnectionsResponse" 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: automation_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/SwitchAutomationConnectionsBody" required: true tags: - Automations "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:removeConnections": post: summary: Remove Automation Connections description: >- Multiple connections can be removed in a single atomic operation. All removals succeed together or all fail together. The automation version is incremented once for all removals. This operation only works on draft automations. To remove connections in a published automation, first use ForkPublishedAutomation to create a draft, then call this method. Per AIP-136, this is a custom method using the :removeConnections suffix. operationId: RemoveAutomationConnections responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1RemoveAutomationConnectionsResponse" 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: automation_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/RemoveAutomationConnectionsBody" required: true tags: - Automations "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:addConnections": post: summary: Add Automation Connections description: >- Multiple connections can be added in a single atomic operation. All additions succeed together or all fail together. The automation version is incremented once for all additions. This operation only works on draft automations. To add connections to a published automation, first use ForkPublishedAutomation to create a draft, then call this method. Per AIP-136, this is a custom method using the :addConnections suffix. operationId: AddAutomationConnections responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1AddAutomationConnectionsResponse" 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: automation_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/AddAutomationConnectionsBody" required: true tags: - Automations "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/visualization": get: summary: Get Automation Visualization operationId: GetAutomationVisualization responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1AutomationVisualization" 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: automation_id in: path required: true schema: type: string tags: - Automations "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/schedule": post: summary: Create Automation Schedule operationId: CreateAutomationSchedule responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1AutomationSchedule" 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: automation_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/v1AutomationSchedule" description: The schedule to create. required: true tags: - Automations patch: summary: Update Automation Schedule operationId: UpdateAutomationSchedule responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1AutomationSchedule" 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: automation_id in: path required: true schema: type: string requestBody: content: application/json: schema: type: object properties: config: $ref: "#/components/schemas/v1ScheduleConfig" enabled: type: boolean description: |- Whether the schedule is currently enabled. Disabled schedules do not trigger automation invocations. readOnly: true summary: type: string title: >- Human-readable summary of the schedule for display in the UI. Generated by the backend based on the schedule configuration. Examples: "Every weekday at 9:00 AM PT", "Monthly on the 4th Friday at 2:30 PM" readOnly: true next_run_times: type: array items: type: string format: date-time description: >- List of the next scheduled execution times. Useful for preview and verification. Backend generates these. readOnly: true remaining_occurrences: type: integer format: int32 description: >- Number of remaining occurrences if the schedule has an end condition. Only populated when config.end.end_type is SCHEDULE_END_TYPE_AFTER_OCCURRENCES. readOnly: true title: The schedule to update. required: - config description: The schedule to update. required: true tags: - Automations get: summary: Get Automation Schedule operationId: GetAutomationSchedule responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1AutomationSchedule" 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: automation_id in: path required: true schema: type: string tags: - Automations delete: summary: Delete Automation Schedule operationId: DeleteAutomationSchedule responses: "200": description: A successful response. content: application/json: schema: type: object properties: {} 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: automation_id in: path required: true schema: type: string tags: - Automations "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:disableAutomationSchedule": post: summary: Disable Automation Schedule operationId: DisableAutomationSchedule responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1DisableAutomationScheduleResponse" 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: automation_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/DisableAutomationScheduleBody" required: true tags: - Automations "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:enableAutomationSchedule": post: summary: Enable Automation Schedule operationId: EnableAutomationSchedule responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1EnableAutomationScheduleResponse" 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: automation_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/EnableAutomationScheduleBody" required: true tags: - Automations "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations:deleteConnection": delete: summary: Delete Workspace Connection description: >- This API validates that the connection is not in use by any published automations before deletion. If only draft automations use the connection, deletion proceeds and returns the list of affected automations. The affected draft automations will have unresolved connection references after deletion. They can still be edited but cannot be published until new connections are configured. Errors: - FAILED_PRECONDITION: Connection is in use by one or more published automations. The error details include DeleteConnectionBlockedError with blocking automations. - NOT_FOUND: Connection not found in the workspace. - INTERNAL: Failed to communicate with the connection storage service. operationId: DeleteWorkspaceConnection responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1DeleteWorkspaceConnectionResponse" 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: connection_id description: The connection ID to delete. in: query required: true schema: type: string tags: - Automations "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/triggers": post: summary: Create Automation Trigger operationId: CreateAutomationTrigger responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1AutomationTrigger" 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: automation_id in: path required: true schema: type: string - name: stage description: |- The automation stage to create the trigger for. Optional; if unset, the service applies its default stage behavior. - AUTOMATION_STAGE_UNSPECIFIED: Automation stage is not specified. - AUTOMATION_STAGE_DRAFT: Automation is in draft stage and can be modified. - AUTOMATION_STAGE_PUBLISHED: Automation is published and immutable, ready for execution. in: query required: false schema: type: string enum: - AUTOMATION_STAGE_UNSPECIFIED - AUTOMATION_STAGE_DRAFT - AUTOMATION_STAGE_PUBLISHED default: AUTOMATION_STAGE_UNSPECIFIED requestBody: content: application/json: schema: $ref: "#/components/schemas/v1AutomationTrigger" description: The trigger phase configuration to store. required: true tags: - Automations get: summary: List Automation Triggers operationId: ListAutomationTriggers responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ListAutomationTriggersResponse" 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: automation_id in: path required: true schema: type: string - name: page_size description: |- The maximum number of triggers to return in a single response. The service may return fewer than this value. If unspecified, a default page size will be used. in: query required: false schema: type: integer format: int32 - name: page_token description: |- A page token received from a previous `ListAutomationTriggers` call. Provide this to retrieve the subsequent page of results. in: query required: false schema: type: string - name: filter description: A filter expression to apply to the list of triggers. in: query required: false schema: type: string tags: - Automations /api/v1/books: get: summary: View Books description: >- This endpoint returns metadata for all books that are currently available in the runtime, including their names, versions, descriptions, authentication requirements, and capabilities. operationId: ListBooks responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2RetrieveBooksResponse" default: description: An unexpected error response. content: application/json: schema: $ref: "#/components/schemas/rpcStatus" parameters: - name: page_size description: The maximum number of books to return. in: query required: false schema: type: integer format: int64 - name: page_token description: The token to use to retrieve the next page of books. in: query required: false schema: type: string - name: filter description: |- AIP-160 Filter expression https://google.aip.dev/160 in: query required: false schema: type: string tags: - Books "/api/v1/books/{name}/{version}": get: summary: View Book Details description: |- This endpoint provides comprehensive metadata about a particular book, including its description, author, icon, authentication mechanisms, configuration parameters, and capabilities. operationId: GetBook responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2RetrieveBookResponse" default: description: An unexpected error response. content: application/json: schema: $ref: "#/components/schemas/rpcStatus" parameters: - name: name in: path required: true schema: type: string - name: version in: path required: true schema: type: string tags: - Books "/api/v1/books/{name}/{version}/procedures": get: summary: View Book Procedures description: >- This endpoint returns a list of all procedures (functions/operations) that can be invoked on the specified book, along with their signatures, input/output parameters, and metadata such as descriptions and examples. operationId: ListBookProcedures responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2RetrieveBookProceduresResponse" default: description: An unexpected error response. content: application/json: schema: $ref: "#/components/schemas/rpcStatus" parameters: - name: name in: path required: true schema: type: string - name: version in: path required: true schema: type: string tags: - Books /api/v1/tags: get: summary: View Tags description: >- This endpoint returns a consolidated list of all tags used across all books in the library. Tags are used for categorizing and organizing books by functionality, domain, or other characteristics. operationId: ListTags responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2RetrieveTagsResponse" default: description: An unexpected error response. content: application/json: schema: $ref: "#/components/schemas/rpcStatus" tags: - Books parameters: [] /api/v1/books:latest: get: summary: View Latest Books description: >- This endpoint returns metadata for all books that are currently available in the runtime, including their names, versions, descriptions, authentication requirements, and capabilities. operationId: ListLatestBooks responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2RetrieveBooksResponse" default: description: An unexpected error response. content: application/json: schema: $ref: "#/components/schemas/rpcStatus" parameters: - name: page_size description: The maximum number of books to return. in: query required: false schema: type: integer format: int64 - name: page_token description: The token to use to retrieve the next page of books. in: query required: false schema: type: string - name: filter description: |- AIP-160 Filter expression https://google.aip.dev/160 in: query required: false schema: type: string tags: - Books "/api/v1/books/{name}/versions": get: summary: View Book Versions description: |- This endpoint returns a list of all version strings available for the specified book name. operationId: ListBookVersions responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2RetrieveBookVersionsResponse" default: description: An unexpected error response. content: application/json: schema: $ref: "#/components/schemas/rpcStatus" parameters: - name: name in: path required: true schema: type: string tags: - Books "/api/v1/books/{name}/{version}/concepts": get: summary: View Book Concepts description: >- This endpoint returns a list of concept descriptors defined by the specified book, which can be referenced by procedures as inputs or outputs. operationId: ListBookConcepts responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2RetrieveBookConceptsResponse" default: description: An unexpected error response. content: application/json: schema: $ref: "#/components/schemas/rpcStatus" parameters: - name: name in: path required: true schema: type: string - name: version in: path required: true schema: type: string tags: - Books "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books": get: summary: View Workspace Books description: >- This endpoint returns metadata for all books that are currently available in the runtime for the specified workspace, including their names, versions, descriptions, authentication requirements, and capabilities. operationId: ListWorkspaceBooks responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2RetrieveBooksResponse" 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 books to return. in: query required: false schema: type: integer format: int64 - name: page_token description: The token to use to retrieve the next page of books. in: query required: false schema: type: string - name: filter description: |- AIP-160 Filter expression https://google.aip.dev/160 in: query required: false schema: type: string tags: - Books "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{name}/{version}/procedures": get: summary: View Workspace Book Procedures description: >- This endpoint returns a list of all procedures (functions/operations) that can be invoked on the specified book in the workspace, along with their signatures, input/output parameters, and metadata such as descriptions and examples. operationId: ListWorkspaceBookProcedures responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2RetrieveBookProceduresResponse" 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: name in: path required: true schema: type: string - name: version in: path required: true schema: type: string tags: - Books "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{name}/{version}/concepts": get: summary: View Workspace Book Concepts description: >- This endpoint returns a list of concept descriptors defined by the specified book in the workspace, which can be referenced by procedures as inputs or outputs. operationId: ListWorkspaceBookConcepts responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2RetrieveBookConceptsResponse" 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: name in: path required: true schema: type: string - name: version in: path required: true schema: type: string tags: - Books "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/connections/{connection_id}/discoverables": get: summary: View Connection Discoverables description: >- This endpoint returns a list of entities (like database tables, API endpoints, file systems, etc.) that can be discovered from a specific book connection and potentially converted into executable procedures. operationId: ListWorkspaceBookConnectionDiscoverables responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2RetrieveDiscoverablesResponse" 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: connection_id in: path required: true schema: type: string - name: search description: A search term to filter the discoverables in: query required: false schema: type: string - name: offset description: >- The starting point within the data set from which records will be returned. Used for pagination. in: query required: false schema: type: string format: uint64 - name: limit description: |- The maximum number of records to return from the data set. Used for pagination. in: query required: false schema: type: string format: uint64 tags: - Books /api/v1/procedures:search: post: summary: Search Book Procedures description: >- This endpoint returns ranked procedures that best match the provided query. Each result includes the owning book name and version, a full procedure descriptor, and a relevance score. operationId: SearchBookProcedures responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2SearchBookProceduresResponse" default: description: An unexpected error response. content: application/json: schema: $ref: "#/components/schemas/rpcStatus" requestBody: content: application/json: schema: $ref: "#/components/schemas/v2SearchBookProceduresRequest" required: true tags: - Books parameters: [] /api/v1/books:search: post: summary: Search Books description: |- This endpoint returns ranked books that best match the provided query. Each result includes a full book descriptor and a relevance score. operationId: SearchBooks responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2SearchBooksResponse" default: description: An unexpected error response. content: application/json: schema: $ref: "#/components/schemas/rpcStatus" requestBody: content: application/json: schema: $ref: "#/components/schemas/v2SearchBooksRequest" required: true tags: - Books parameters: [] /api/v1/concepts:search: post: summary: Search Book Concepts description: >- This endpoint returns ranked concepts that best match the provided query. Each result includes the owning book name, version, a full concept descriptor, and a relevance score. operationId: SearchBookConcepts responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2SearchBookConceptsResponse" default: description: An unexpected error response. content: application/json: schema: $ref: "#/components/schemas/rpcStatus" requestBody: content: application/json: schema: $ref: "#/components/schemas/v2SearchBookConceptsRequest" required: true tags: - Books parameters: [] "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/procedures:search": post: summary: Search Workspace Book Procedures description: >- This endpoint returns ranked procedures that best match the provided query. Each result includes the owning book name and version, a full procedure descriptor, and a relevance score. operationId: SearchWorkspaceBookProcedures responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2SearchWorkspaceBookProceduresResponse" 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 requestBody: content: application/json: schema: $ref: "#/components/schemas/SearchWorkspaceBookProceduresBody" required: true tags: - Books "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/connections/{connection_id}/procedures:search": post: summary: Search Connection Procedures description: >- This endpoint returns ranked procedures that best match the provided query. Each result includes the owning book name and version, a full procedure descriptor, and a relevance score. operationId: SearchWorkspaceBookConnectionProcedures responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2SearchWorkspaceBookProceduresResponse" 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: connection_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/SearchWorkspaceBookConnectionProceduresBody" required: true tags: - Books "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books:search": post: summary: Search Workspace Books description: |- This endpoint returns ranked books that best match the provided query. Each result includes a full book descriptor and a relevance score. operationId: SearchWorkspaceBooks responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2SearchBooksResponse" 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 requestBody: content: application/json: schema: $ref: "#/components/schemas/SearchWorkspaceBooksBody" required: true tags: - Books "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/concepts:search": post: summary: Search Workspace Book Concepts description: >- This endpoint returns ranked concepts that best match the provided query. Each result includes the owning book name, version, a full concept descriptor, and a relevance score. operationId: SearchWorkspaceBookConcepts responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2SearchBookConceptsResponse" 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 requestBody: content: application/json: schema: $ref: "#/components/schemas/SearchWorkspaceBookConceptsBody" required: true tags: - Books "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/{book_version}/connections": post: summary: Create Book Connection description: |- This endpoint adds a new book connection, which can be used to invoke procedures on the book. operationId: AddWorkspaceBookConnection responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2BookConnectionResponse" 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: book_name in: path required: true schema: type: string - name: book_version in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/AddWorkspaceBookConnectionBody" required: true tags: - Books get: summary: View Book Connections description: This endpoint returns a list of all connections of a book version. operationId: ListWorkspaceBookConnections responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2RetrieveBookConnectionsResponse" 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: book_name in: path required: true schema: type: string - name: book_version in: path required: true schema: type: string - name: page_size description: The maximum number of connections to return. in: query required: false schema: type: integer format: int64 - name: page_token description: The token to use to retrieve the next page of connections. in: query required: false schema: type: string tags: - Books "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/{book_version}/connections/{connection_id}": put: summary: Update Book Connection description: This endpoint updates a book connection in the library. operationId: UpdateWorkspaceBookConnection responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2BookConnectionResponse" 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: book_name in: path required: true schema: type: string - name: book_version in: path required: true schema: type: string - name: connection_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/UpdateWorkspaceBookConnectionBody" required: true tags: - Books "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/connections/{connection_id}": get: summary: View Connection description: This endpoint returns a specific book connection. operationId: GetWorkspaceBookConnection responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2RetrieveBookConnectionResponse" 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: connection_id in: path required: true schema: type: string tags: - Books "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/connections": get: summary: View All Connections operationId: ListAllWorkspaceBookConnections responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2RetrieveBooksConnectionsResponse" 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 connections to return. in: query required: false schema: type: integer format: int64 - name: page_token description: The token to use to retrieve the next page of connections. in: query required: false schema: type: string - name: filter description: |- AIP-160 Filtering https://google.aip.dev/160 in: query required: false schema: type: string tags: - Books "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/{book_version}/connections/{connection_id}/upgrade": put: summary: Upgrade Book Connection description: This endpoint upgrades a book connection to a new version. operationId: UpgradeWorkspaceBookConnection responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2BookConnectionResponse" 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: book_name in: path required: true schema: type: string - name: book_version in: path required: true schema: type: string - name: connection_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/UpgradeWorkspaceBookConnectionBody" required: true tags: - Books "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/connections/{connection_id}/authorize": put: summary: Authorize Connection description: This endpoint generates a new authrization url for an existing book connection. operationId: AuthorizeWorkspaceBookConnection responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2BookConnectionResponse" 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: connection_id in: path required: true schema: type: string tags: - Books "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/connections/{connection_id}/discover": post: summary: Discover Connection Procedures description: >- This endpoint allows books to discover and register new procedures at runtime by connecting to external APIs, databases, or services. The discovered procedures become available for invocation. Supports: - Specification of what entities to discover - Dynamic procedure registration Note: This will override any existing discoverables, and sending an empty list will remove all discoverables. operationId: SetDiscovered responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2DiscoverWorkspaceBookConnectionProceduresResponse" 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: connection_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/SetDiscoveredBody" required: true tags: - Books "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/connections/{connection_id}/procedures": get: summary: View Connection Procedures description: >- This endpoint returns a list of all procedures (functions/operations) that can be invoked on the specified book connection in the workspace, along with their signatures, input/output parameters, and metadata such as descriptions and examples. operationId: ListWorkspaceBookConnectionProcedures responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2RetrieveBookProceduresResponse" 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: connection_id in: path required: true schema: type: string - name: procedure_ids description: |- Exact procedure identifiers to retrieve (static or discovered). Empty preserves the legacy behavior of returning all procedures. Unknown identifiers are omitted; duplicates do not duplicate results. Deploy a filter-aware LibraryService before clients rely on bounded responses. in: query required: false explode: true schema: type: array items: type: string tags: - Books "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/{book_version}/connections/{connection_id}/triggers": post: summary: Create Trigger Instance operationId: AddWorkspaceBookConnectionTriggerInstance responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2AddWorkspaceBookConnectionTriggerInstanceResponse" 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: book_name in: path required: true schema: type: string - name: book_version in: path required: true schema: type: string - name: connection_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/AddWorkspaceBookConnectionTriggerInstanceBody" required: true tags: - Books "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/triggers/{trigger_instance_id}/automations": post: summary: Set Trigger Automations operationId: SetAutomationsForTriggerInstance responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2SetAutomationsForTriggerInstanceResponse" 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: trigger_instance_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/SetAutomationsForTriggerInstanceBody" required: true tags: - Books put: summary: Set Automations For Trigger Instance description: |- Attach automations to a trigger instance. The caller sends the full desired list; the existing list is replaced. Both POST and PUT are accepted at the same path. PUT is preferred and matches the replace-collection semantics; the POST binding is retained for backwards compatibility and may be removed in a future version. operationId: SetWorkspaceAutomationsForTriggerInstance responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2SetAutomationsForTriggerInstanceResponse" default: description: An unexpected error response. content: application/json: schema: $ref: "#/components/schemas/rpcStatus" parameters: - name: organization_id description: The id of the organization in: path required: true schema: type: string - name: workspace_id description: The id of the workspace in: path required: true schema: type: string - name: trigger_instance_id description: The identifier of the trigger instance in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/LibraryServiceSetAutomationsForTriggerInstanceBody" required: true tags: - Books "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/connections/{connection_id}/triggers/{trigger_instance_id}": delete: summary: Delete Trigger Instance operationId: RemoveWorkspaceBookConnectionTriggerInstance responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2RemoveWorkspaceBookConnectionTriggerInstanceRespo\ nse" 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: connection_id in: path required: true schema: type: string - name: trigger_instance_id in: path required: true schema: type: string tags: - Books put: summary: Update Workspace Book Connection Trigger Instance description: |- Updates an existing trigger instance's name, configuration, and filter expression. Uses PUT semantics - all fields are required and will replace the existing values. operationId: UpdateWorkspaceBookConnectionTriggerInstance responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2UpdateWorkspaceBookConnectionTriggerInstanceResponse" default: description: An unexpected error response. content: application/json: schema: $ref: "#/components/schemas/rpcStatus" parameters: - name: organization_id description: The id of the organization in: path required: true schema: type: string - name: workspace_id description: The id of the workspace in: path required: true schema: type: string - name: connection_id description: The identifier of the book connection in: path required: true schema: type: string - name: trigger_instance_id description: The identifier of the trigger instance to update in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/LibraryServiceUpdateWorkspaceBookConnectionTriggerInstanceBody" required: true tags: - Books "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/triggers": get: summary: View Trigger Instances operationId: ListWorkspaceTriggerInstances responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2RetrieveWorkspaceTriggerInstancesResponse" 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: filter description: |- AIP-160 Filter expression https://google.aip.dev/160 in: query required: false schema: type: string tags: - Books "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/connections/{connection_id}/user-info": get: summary: View Connection User Info description: >- This endpoint returns information about the user (email, username and other extra attributes) from a book that has already been connected. operationId: GetWorkspaceBookConnectionUserInfo responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2RetrieveUserInfoResponse" 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: connection_id in: path required: true schema: type: string tags: - Books "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}": get: summary: Get Run operationId: GetRun responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Run" 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: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string tags: - Runs "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs": get: summary: List Runs operationId: ListRuns responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ListRunsResponse" 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: automation_id in: path required: true schema: type: string - name: page_size description: >- The maximum number of runs to return in a single response. The service may return fewer than this value. If unspecified or 0, at most 10 runs will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. If negative, an INVALID_ARGUMENT error will be returned. in: query required: false schema: type: integer format: int32 - name: page_token description: >- A page token received from a previous `ListRuns` call. Provide this to retrieve the subsequent page of results. When paginating, all other parameters provided to `ListRuns` must match the call that provided the page token. in: query required: false schema: type: string - name: filter description: |- Filter expression for filtering runs. Follows the structured syntax defined in AIP-160. Supported fields and operators for filtering: - create_time: The timestamp when the run was created (google.protobuf.Timestamp). Supports =, !=, <, >, <=, >=. - previous_run: The run that was replayed to produce this run (string). Supports = and != with a run resource name or an empty string. Filter for an empty value to return only top-level runs (those not produced by a replay). - root_run: The first run in this run's replay lineage (string). Supports = and != with a run resource name. Filter by a run name to return that run together with every replay derived from it. - runState: The current execution state of the run. Supports = and !=. Valid values: Created, Pending, Executing, Stopped, NeedsWakeup, WaitingForTimer, NeedsGuidance, WaitingForGuidance, WaitingForBook, Completed. - stage: The automation stage for the run. Supports = and !=. Valid values: Draft, Published. - automation_id: The automation identifier for the run. Supports =. - stage_version: The automation stage version for the run. Supports = and !=. - invocation_source: The entity that initiated the run. Supports = and !=. Valid values: Unspecified, Manual, Trigger, Schedule, Test, Pat, or the corresponding InvocationSource enum names. - archived: Whether the run has been archived. Supports = with unquoted boolean values true or false. If omitted, only non-archived runs are returned. - search: Free-text search. Supports only the : (has) operator, which matches a case-insensitive substring. Unlike every other field this does not name a column; the term is matched against, in one pass: * every input name and value (runs created before user_inputs existed, and multi-step runs other than a PRE -> MAIN handoff, have no stored inputs and so cannot match on them), * every output name and value of a completed run, * the run id, stage version, invocation source and initiating user id, * the display labels of invocation source and run state, so "personal access token" matches a run stored as "pat", * the text inside the run's files, when the term has at least 3 characters (content search, below). Not matched: numeric values, because a number persists as a mantissa plus a flags bitfield and decoding it per row is too expensive for a keyword scan; and values offloaded to object storage, whose content is not in the database, except offloaded text, which content search reads. A file matches on its name when stored inline, and on its resource path when offloaded. A term longer than 256 characters is rejected. Several search terms may be combined with AND; each must match somewhere. Content search matches the term, case-insensitively, against text extracted from the files in the run's inputs, outputs and trigger payload (every email attachment included), from offloaded text values, and, through the Run log, from the files the run's steps used and the text they produced, such as the fields a document-processing book extracted. A run that matches this way has an entry in ListRunsResponse.content_matches naming the file and where in it the term was found, never the matched text. Content search has these limits: * only Published runs are indexed, so a Draft run matches on its values only, * an organization that opted out of content search gets values-only search, * files are indexed in the background, so a file becomes searchable some time after the run records it, typically within minutes, * pages without a text layer, such as scans and images, are not searchable because no OCR is run; Run.content_coverage counts each run's files that are not searchable, and why. Supported logical operators: - AND may combine conditions across fields. - OR may combine conditions for the same field only. Examples: - Filter runs created after a specific date (start_date): "create_time >= \"2024-01-01T00:00:00Z\"" - Only top-level runs (exclude replays): "previous_run = \"\"" - A run and its full replay lineage: "root_run = \"organizations/1/workspaces/2/automations/3/runs/4\"" - Filter runs created before a specific date (end_date): "create_time <= \"2024-12-31T23:59:59Z\"" - Filter runs within a date range (start_date and end_date): "create_time >= \"2024-01-01T00:00:00Z\" AND create_time <= \"2024-12-31T23:59:59Z\"" - Filter runs in specific states: "runState = \"Executing\" OR runState = \"Pending\"" - Filter published runs from a specific stage version: "stage = \"Published\" AND stage_version = \"2\"" - Filter by invocation source: "invocation_source = \"INVOCATION_SOURCE_MANUAL\"" - Include only archived runs: "archived = true" - Find the run that produced a particular output value: "search : \"ZIMUBKK80482811\"" - Narrow a free-text search to a date range: "search : \"INV-90210\" AND create_time >= \"2024-01-01T00:00:00Z\"" - Find the run whose attached PDF mentions a purchase order number: "search : \"PO-4471\"" Timestamps must be in RFC-3339 format (e.g., "2024-01-01T00:00:00Z"). If an invalid filter expression is provided, the API will return INVALID_ARGUMENT. in: query required: false schema: type: string - name: order_by description: |- Sort order for the returned runs. Follows AIP-132 ordering syntax. Supported fields for ordering: - create_time: The timestamp when the run was created Syntax: " ", where direction is "asc" or "desc". Examples: - "create_time desc" (newest first) - "create_time asc" (oldest first) If unspecified, results are ordered by create_time descending (newest first), preserving existing behavior. An unsupported field or direction returns INVALID_ARGUMENT. in: query required: false schema: type: string tags: - Runs post: summary: Create Run description: |- Creates a new run with the specified executable code and inputs. The run will be queued for execution and assigned a unique identifier. operationId: CreateRun responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Run" 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: automation_id in: path required: true schema: type: string - name: request_id description: |- Client-supplied UUID4 idempotency token for CreateRun. When set, Jeeves returns the existing run for the same (org, workspace, automation, request_id) within the retention window instead of creating a duplicate. in: query required: false schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/v1Run" description: The run to be created, including executable code, inputs, and dependencies. required: true tags: - Runs "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}:pause": post: summary: Pause Run operationId: PauseRun responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Run" 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: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/PauseRunBody" required: true tags: - Runs "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}:continue": post: summary: Continue Run operationId: ContinueRun responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Run" 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: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/ContinueRunBody" required: true tags: - Runs "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}:automationRunAggregates": get: summary: Query Automation Run Aggregates operationId: QueryAutomationRunAggregates responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1QueryAutomationRunAggregatesResponse" 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: - Runs "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}:dailyRunAggregates": get: summary: Query Daily Run Aggregates operationId: QueryDailyRunAggregates responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1QueryDailyRunAggregatesResponse" 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: start_date.year description: >- Year of the date. Must be from 1 to 9999, or 0 to specify a date without a year. in: query required: false schema: type: integer format: int32 - name: start_date.month description: >- Month of a year. Must be from 1 to 12, or 0 to specify a year without a month and day. in: query required: false schema: type: integer format: int32 - name: start_date.day description: >- Day of a month. Must be from 1 to 31 and valid for the year and month, or 0 to specify a year by itself or a year and month where the day isn't significant. in: query required: false schema: type: integer format: int32 - name: end_date.year description: >- Year of the date. Must be from 1 to 9999, or 0 to specify a date without a year. in: query required: false schema: type: integer format: int32 - name: end_date.month description: >- Month of a year. Must be from 1 to 12, or 0 to specify a year without a month and day. in: query required: false schema: type: integer format: int32 - name: end_date.day description: >- Day of a month. Must be from 1 to 31 and valid for the year and month, or 0 to specify a year by itself or a year and month where the day isn't significant. in: query required: false schema: type: integer format: int32 - name: time_zone description: >- Time zone for date aggregation. Format: IANA timezone identifier (e.g., "America/New_York", "UTC", "Europe/London") in: query required: true schema: type: string - name: filter description: >- Filter expression for filtering runs included in the aggregation. Follows the structured syntax defined in AIP-160. Supported fields for filtering: - automation_id: The unique identifier of the automation (string) Supported operators: - Comparison: = - Logical: OR Examples: - Filter by specific automation: "automation_id = \"789\"" - Filter by multiple automations: "automation_id = \"789\" OR automation_id = \"790\"" If an invalid filter expression is provided, the API will return INVALID_ARGUMENT. in: query required: false schema: type: string tags: - Runs "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/dashboards:configureAutomationEstimates": post: summary: Configure Automation Estimates operationId: ConfigureAutomationEstimates responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/dashboardsConfigureAutomationEstimatesResponse" 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 requestBody: content: application/json: schema: $ref: "#/components/schemas/ConfigureAutomationEstimatesBody" required: true tags: - Analytics "/api/v1/organizations/{organization_id}/dashboards:queryInsights": get: summary: Query Insights operationId: QueryInsights responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/dashboardsQueryInsightsResponse" 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: filter.workspace_ids description: |- Optional list of workspace IDs to filter insights. Format: organizations/{organization}/workspaces/{workspace} If empty, insights for all workspaces are returned. in: query required: false explode: true schema: type: array items: type: string - name: filter.automation_ids description: >- Optional list of automation IDs to filter insights. Format: organizations/{organization}/workspaces/{workspace}/automations/{automation} If empty, insights for all automations are returned. in: query required: false explode: true schema: type: array items: type: string - name: filter.time_window.start_time description: The start time of the window (inclusive). in: query required: true schema: type: string format: date-time - name: filter.time_window.end_time description: The end time of the window (inclusive). in: query required: true schema: type: string format: date-time - name: filter.time_window.time_zone description: >- The timezone for interpreting the time window. Format: IANA timezone identifier (e.g., "America/New_York", "Europe/London"). Defaults to "UTC" if not specified. in: query required: false schema: type: string tags: - Analytics "/api/v1/organizations/{organization_id}/dashboards:queryAutomationEstimates": get: summary: Query Automation Estimates operationId: QueryAutomationEstimates responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/dashboardsQueryAutomationEstimatesResponse" 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 tags: - Analytics "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/executions/{execution_id}/outputs": get: summary: Get Execution Outputs operationId: GetExecutionOutputs responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1GetExecutionOutputsResponse" 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: execution_id in: path required: true schema: type: string tags: - Runs "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/events": get: summary: List Run Events description: >- This RPC retrieves a paginated list of all events that occurred during a specific automation run. Events are returned in the order they were generated, providing a complete timeline of the run's execution. Use the filter parameter to narrow results by specific criteria such as node_kind for execution journal events. The response includes both high-level run state changes (starts, completions, failures) and detailed execution steps (node executions, execution patches, detailed data flows in each expression, etc). operationId: ListRunEvents responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ListRunEventsResponse" 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: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string - name: page_size description: |- Maximum number of run events to return in a single response. The service may return fewer events than requested, but will never return more. This can happen when: - The run has fewer total events than requested - Internal chunking limits are reached - The remaining events don't fit in the response size limit Valid range: 1-1000 events Default: 100 events if unspecified Values above 1000 are automatically capped at 1000 Negative values result in an INVALID_ARGUMENT error in: query required: false schema: type: integer format: int32 - name: page_token description: |- Pagination token from a previous ListRunEvents response. Provide the `next_page_token` value from a previous response to continue retrieving the next set of events. Leave empty or unset for the first page of results. The token is opaque and should not be parsed or modified by clients. in: query required: false schema: type: string - name: filter description: |- Filter expression to narrow down which events are returned. Uses AIP-160 filtering syntax (https://google.aip.dev/160). Supported fields: node_kind (string) — AST node kind, e.g. node_kind = "FunctionCall" start_line (integer) — 0-based start line of the node's source location end_line (integer) — 0-based end line (exclusive) of the node's source location Events without the filtered field are excluded from results. When empty or unset, all events for the specified run are returned. in: query required: false schema: type: string - name: order_by description: |- Ordering of the returned events. Follows AIP-132 syntax (https://google.aip.dev/132#ordering). The only sortable field is "time" (the event timestamp). Accepted values: "time asc" or "time desc". Default: "time asc" (chronological order, oldest first). Example: order_by="time desc" returns newest events first. Pagination cursors are direction-aware: a page_token obtained with one ordering must not be reused with a different ordering. in: query required: false schema: type: string tags: - Runs "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/files:upload": post: summary: Upload File description: |- Upload a file scoped to a specific workspace. The file's lifetime is tied to the organization. This is the preferred endpoint for new file uploads. operationId: UploadFile responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1UploadFileResponse" "201": description: File uploaded successfully headers: Location: description: URL of the created file resource schema: type: string content: application/json: schema: {} 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 requestBody: content: multipart/form-data: schema: $ref: "#/components/schemas/apiHttpBody" description: Raw HTTP body containing multipart/form-data required: true tags: - Files x-requestBody: content: multipart/form-data: schema: properties: content: description: File content format: binary type: string filename: description: Original filename type: string required: - filename - content type: object description: File upload data required: true "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/files/{file}:download": get: summary: Download File operationId: DownloadFile responses: "200": description: File content headers: Content-Disposition: description: Attachment with filename schema: type: string Content-Length: description: File size in bytes schema: type: string Content-Type: description: MIME type of the file schema: type: string content: application/octet-stream: schema: type: string format: binary default: description: An unexpected error response. content: application/octet-stream: 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: file in: path required: true schema: type: string tags: - Files "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/files/{file}/metadata": get: summary: Get File Metadata operationId: GetFileMetadata responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1FileMetadata" 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: file in: path required: true schema: type: string tags: - Files "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/files/{file}": delete: summary: Delete File operationId: DeleteFile responses: "200": description: A successful response. content: application/json: schema: type: object properties: {} 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: file in: path required: true schema: type: string tags: - Files "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/files:generateUploadUrl": post: summary: Generate Upload Url operationId: GenerateUploadUrl responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1GenerateUploadUrlResponse" 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 requestBody: content: application/json: schema: $ref: "#/components/schemas/GenerateUploadUrlBody" required: true tags: - Files "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/files/{file}:generateDownloadUrl": post: summary: Generate Download Url operationId: GenerateDownloadUrl responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1GenerateDownloadUrlResponse" 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: file in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/GenerateDownloadUrlBody" required: true tags: - Files "/api/v1/organizations/{organization_id}/metrics:query": get: summary: Query Metrics description: >- This RPC retrieves time-series metric data for a specific organization, supporting multiple metrics in a single request. Results can be filtered, grouped, and sorted by tag dimensions. The response contains one result per requested metric. Each result includes multiple time series (one per unique group_by combination), with each series containing chronologically ordered data points showing the aggregated metric value over time. Use the filter parameter (AIP-160 syntax) to restrict data to specific tag values, and group_by to break down results by tag dimensions. The order_by and page_size parameters enable sorting and limiting results (useful for "top N" queries). The interval and aggregation parameters control how data is aggregated. If not specified, the server will determine appropriate defaults based on the time range. Example use cases: - Dashboard view: metrics=["runs", "pages"], group_by=["status"] - Top 10 workspaces: metrics=["runs"], group_by=["workspace_id"], order_by="value desc", page_size=10 - Success rate: metrics=["runs"], filter='status = "success"' - Multi-metric comparison: metrics=["files", "automations"], group_by=["workspace_id"] operationId: QueryMetrics responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1QueryMetricsResponse" 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: metrics description: >- The names of the metrics to query. Identifies which metric types to retrieve data for in a single request. All metrics will use the same filter, group_by, time range, interval, and aggregation settings. Examples: ["runs"], ["runs", "pages"], ["files", "automations"] in: query required: true explode: true schema: type: array items: type: string - name: filter description: |- Filter expression to apply before aggregation. Reduces the dataset to only records matching the filter criteria. Uses the AIP-160 filtering syntax for flexible query expressions. An empty string means no filtering (all records included). Supported operators: =, !=, AND, OR, NOT, IN Examples: - 'status = "success"' - 'status = "success" AND workspace_id = "ws_123"' - 'status IN ["success", "pending"]' - 'workspace_id = "ws_123" OR workspace_id = "ws_456"' See https://google.aip.dev/160 for full syntax specification. in: query required: false schema: type: string - name: group_by description: >- Tag dimensions to group results by. Each unique combination of these tag values becomes a separate time series. An empty list means no grouping (single aggregated series). Examples: ["status"], ["workspace_id", "status"] in: query required: false explode: true schema: type: array items: type: string - name: start_time description: |- Start time for the query range (inclusive). Data points with timestamps on or after this time will be included. in: query required: true schema: type: string format: date-time - name: end_time description: |- End time for the query range (exclusive). Data points with timestamps before this time will be included. in: query required: true schema: type: string format: date-time - name: interval description: >- Requested time interval for aggregation. Specifies the desired granularity for data points. The server may adjust this based on the time range or data availability. If unspecified, the server will determine an appropriate interval. - METRIC_INTERVAL_UNSPECIFIED: Unspecified interval. Server will determine appropriate interval. - METRIC_INTERVAL_HOUR: Hourly aggregation. - METRIC_INTERVAL_DAY: Daily aggregation. - METRIC_INTERVAL_WEEK: Weekly aggregation. - METRIC_INTERVAL_MONTH: Monthly aggregation. in: query required: false schema: type: string enum: - METRIC_INTERVAL_UNSPECIFIED - METRIC_INTERVAL_HOUR - METRIC_INTERVAL_DAY - METRIC_INTERVAL_WEEK - METRIC_INTERVAL_MONTH default: METRIC_INTERVAL_UNSPECIFIED - name: aggregation description: >- Aggregation function to apply to metric values. Specifies how values should be combined within each interval. If unspecified, defaults to COUNT. - AGGREGATION_FUNCTION_UNSPECIFIED: Unspecified aggregation. Defaults to COUNT. - AGGREGATION_FUNCTION_COUNT: Count of occurrences. - AGGREGATION_FUNCTION_SUM: Sum of values. - AGGREGATION_FUNCTION_AVG: Average of values. - AGGREGATION_FUNCTION_MIN: Minimum value. - AGGREGATION_FUNCTION_MAX: Maximum value. in: query required: false schema: type: string enum: - AGGREGATION_FUNCTION_UNSPECIFIED - AGGREGATION_FUNCTION_COUNT - AGGREGATION_FUNCTION_SUM - AGGREGATION_FUNCTION_AVG - AGGREGATION_FUNCTION_MIN - AGGREGATION_FUNCTION_MAX default: AGGREGATION_FUNCTION_UNSPECIFIED - name: order_by description: >- Ordering for series results within each metric. Uses AIP-132 syntax: "field_name [asc|desc]" Multiple orderings can be comma-separated. Supported fields: - Tag names from group_by (e.g., "workspace_id asc", "status desc") - "value" for sorting by aggregated metric value (uses last data point) Examples: - "value desc" - Highest values first (e.g., top workspaces) - "workspace_id asc" - Alphabetical by workspace ID - "value desc, workspace_id asc" - By value descending, then workspace ascending If unspecified, series are returned in arbitrary order. See https://google.aip.dev/132 for full syntax specification. in: query required: false schema: type: string - name: page_size description: >- Maximum number of series to return per metric. Limits the number of time series in each metric's results. Useful with order_by for "top N" queries. If unspecified or zero, all matching series are returned. If page_size is larger than the number of matching series, all series are returned. Example: order_by="value desc", page_size=10 returns top 10 series. in: query required: false schema: type: integer format: int32 - name: page_token description: >- Pagination token for retrieving the next page of series. When a response contains more series than page_size, the next_page_token from the response can be passed here to retrieve the next page. If empty, returns the first page of results. See https://google.aip.dev/158 for pagination specification. in: query required: false schema: type: string tags: - Analytics "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/exceptions/{exception_id}": get: summary: Get Exception operationId: GetException responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Exception" 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: exception_id in: path required: true schema: type: string tags: - Exceptions "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/exceptions": get: summary: List Exceptions operationId: ListExceptions responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ListExceptionsResponse" 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 exceptions to return. The service may return fewer than this value. If unspecified, at most 50 exceptions will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. Note: These limits are enforced by server-side validation. in: query required: false schema: type: integer format: int32 - name: page_token description: >- The page token, received from a previous `ListExceptions` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `ListExceptions` must match the call that provided the page token. in: query required: false schema: type: string - name: skip description: The number of exceptions to skip before returning results. in: query required: false schema: type: integer format: int32 - name: filter description: >- The filter to apply to the list of exceptions. Follows Google AIP-160 filtering standard (https://google.aip.dev/160). Supported Fields: - state: Exception state (PENDING, RESOLVED, ARCHIVED) - automation: Automation ID (exact match only) - create_time: Exception creation timestamp (ISO 8601 format) - group: Exception group (exact match only) - Use group = "value" to match a specific group - Use group = "" to match exceptions with no group assigned (ungrouped) - run: Run ID (exact match only) - Use run = "run1_id" to match a specific run - Use run = "run1_id OR run2_id" to match multiple runs Supported Operators: - Comparison: =, !=, <, <=, >, >= - Logical: AND, OR, NOT - Grouping: ( ) State Values: - PENDING or EXCEPTION_STATE_PENDING - RESOLVED or EXCEPTION_STATE_RESOLVED - ARCHIVED or EXCEPTION_STATE_ARCHIVED Timestamp Format: - ISO 8601 with Z suffix: "2025-01-01T00:00:00Z" - ISO 8601 with offset: "2025-01-01T00:00:00+00:00" Example Filters: - "state = PENDING" - List only pending exceptions - "state != RESOLVED" - List all non-resolved exceptions - "automation = my-automation-id" - List exceptions for a specific automation - "state = PENDING AND automation = my-automation-id" - Pending exceptions for an automation - "state = PENDING OR state = ARCHIVED" - Pending or archived exceptions - "NOT state = RESOLVED" - All non-resolved exceptions - "create_time > \"2025-01-01T00:00:00Z\"" - Exceptions created after Jan 1, 2025 - "create_time >= \"2025-01-01T00:00:00Z\" AND create_time < \"2025-02-01T00:00:00Z\"" - January 2025 exceptions - "(state = PENDING OR state = ARCHIVED) AND create_time > \"2025-01-01T00:00:00Z\"" - Recent unresolved exceptions - "group = \"missing_values\"" - List exceptions in exactly the missing_values group - "group = \"missing_values\" OR group = \"user_system_error\"" - List exceptions in multiple groups - "group = \"\"" - List ungrouped exceptions (no group assigned) - "state = PENDING AND group = \"\"" - List pending ungrouped exceptions - "group != \"\"" - List all exceptions that have a group assigned (any group) - "run = run1_id OR run = run2_id" - List exceptions for multiple runs - "run = run1_id" - List exceptions for a specific run in: query required: false schema: type: string tags: - Exceptions "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/{agent_id}/events": post: summary: Create Event operationId: CreateEvent responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Event" 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: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string - name: agent_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/v1Event" description: >- The event to create. IMPORTANT: Only user_message can be set when creating an event. The API will reject requests that attempt to create events with agent_message, tool_call, thinking, or system_message set. These event types are automatically created by the system. required: true tags: - Exceptions get: summary: List Events operationId: ListEvents responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ListEventsResponse" 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: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string - name: agent_id in: path required: true schema: type: string - name: page_size description: >- The maximum number of events to return. The service may return fewer than this value. If unspecified, at most 50 events will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. Note: These limits are enforced by server-side validation. in: query required: false schema: type: integer format: int32 - name: page_token description: >- The page token, received from a previous `ListEvents` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `ListEvents` must match the call that provided the page token. in: query required: false schema: type: string - name: filter description: >- The filter to apply to the list of events. Follows Google AIP-160 filtering standard (https://google.aip.dev/160). Supported Fields: - exception: Exception Id Supported Operators: - Comparison: =, != - Logical: AND, OR, NOT - Grouping: ( ) Example Filters: - "exception = \"exc-123\"" - Events for a specific exception - "exception = \"exc-123\" OR exception = \"exc-456\"" - Events for multiple exceptions in: query required: false schema: type: string tags: - Exceptions "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/{agent_id}/events/{event_id}": get: summary: Get Event operationId: GetEvent responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Event" 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: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string - name: agent_id in: path required: true schema: type: string - name: event_id in: path required: true schema: type: string tags: - Exceptions "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/{agent_id}/events:stream": get: summary: Stream Events operationId: StreamEvents responses: "200": description: NDJSON stream of StreamEventsResponse objects (one JSON object per line) content: application/x-ndjson: schema: type: string format: binary title: NDJSON stream of StreamEventsResponse objects default: description: An unexpected error response. content: application/x-ndjson: 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: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string - name: agent_id in: path required: true schema: type: string tags: - Exceptions "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/{agent_id}/events:cancelGeneration": post: summary: Cancel Generation operationId: CancelGeneration responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1CancelGenerationResponse" 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: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string - name: agent_id in: path required: true schema: type: string tags: - Exceptions "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/exceptionGroups": get: summary: List Exception Groups operationId: ListExceptionGroups responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ListExceptionGroupsResponse" 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 groups to return. Note: Since groups are static and typically small in number, pagination is not strictly necessary but included for AIP compliance. in: query required: false schema: type: integer format: int32 - name: page_token description: The page token from a previous ListExceptionGroups call. in: query required: false schema: type: string tags: - Exceptions "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/exceptions:countByGroup": get: summary: Count Exceptions By Group operationId: CountExceptionsByGroup responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1CountExceptionsByGroupResponse" 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: filter description: >- Optional filter to apply before counting (same syntax as ListExceptions). Use this to count within a specific state, automation, time range, etc. Example: "state = PENDING" to count only pending exceptions by group. in: query required: false schema: type: string - name: page_size description: >- The maximum number of groups to return. If unspecified, at most 50 groups 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: The page token from a previous CountExceptionsByGroup call. in: query required: false schema: type: string tags: - Exceptions "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/exceptions:countByAutomation": get: summary: Count Exceptions By Automation operationId: CountExceptionsByAutomation responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1CountExceptionsByAutomationResponse" 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: filter description: >- Optional filter to apply before counting (same syntax as ListExceptions). Use this to count within a specific state, group, time range, etc. Example: "state = PENDING" to count only pending exceptions by automation. Example: "group = \"missing_values\"" to count exceptions in missing_values group by automation. in: query required: false schema: type: string - name: page_size description: >- The maximum number of automations to return. If unspecified, at most 50 automations 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: The page token from a previous CountExceptionsByAutomation call. in: query required: false schema: type: string tags: - Exceptions "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/guideEntries/{guide_entry_id}": get: summary: Get Guide Entry operationId: GetGuideEntry responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1GuideEntry" 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: automation_id in: path required: true schema: type: string - name: guide_entry_id in: path required: true schema: type: string tags: - Exceptions patch: summary: Update Guide Entry description: |- Updates a TSG entry. Only the content field can be updated. operationId: UpdateGuideEntry responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1GuideEntry" 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: automation_id in: path required: true schema: type: string - name: guide_entry_id in: path required: true schema: type: string - name: update_mask description: |- The list of fields to update. If empty or unset, all mutable fields will be updated. Mutable fields: - "title": Guide entry title - "root_cause": Root cause description - "resolution_steps": Resolution action and steps (Markdown) - "resolution_code": Example resolution code - "resolution_notes": Additional resolution notes (Markdown) - "content": (DEPRECATED) Use resolution_steps, resolution_code, and resolution_notes instead in: query required: false schema: type: string - name: user description: |- The acting user, used by the server to attribute the new version row produced by this update. Format: users/{user} Optional: when omitted, the new version has no update attribution (the audit column is left NULL). Internal and test callers that do not carry a user identity can omit it. in: query required: false schema: type: string requestBody: content: application/json: schema: type: object properties: content: type: string description: |- Markdown-formatted entry content Deprecated: Use resolution_steps and resolution_code instead. source_exception: type: string title: Exception that led to this entry's creation source_run: type: string title: Run where this entry was first created create_time: type: string format: date-time title: Creation timestamp readOnly: true update_time: type: string format: date-time title: Last update timestamp readOnly: true delete_time: type: string format: date-time description: |- The time when this guide entry was soft-deleted. If not set, the entry has not been deleted. Soft-deleted entries are not physically removed but marked as deleted. Always set the state to STATE_ARCHIVED whenever the entry is soft-deleted. readOnly: true title: type: string description: |- Title of the guide entry Marked as optional for backwards compatibility. Can be set when creating or updating the guide entry. automation: type: string title: |- The automation that the guide entry belongs to. Format: organizations/{organization}/workspaces/{workspace}/automations/{automation} readOnly: true root_cause: type: string description: |- Root cause analysis explaining why the exception occurred. This provides technical context about what caused the issue. Marked as optional for backwards compatibility. state: $ref: "#/components/schemas/v1GuideEntryState" version: type: string title: |- Semantic version of this specific version of the guide entry (format: major.minor). Incremented each time the guide entry is updated. Examples: "0.1", "1.0", "1.1", "2.0" readOnly: true resolution_steps: type: string description: |- Human-readable explanation of the resolution action and steps. GitHub Flavored Markdown (GFM) formatted. Resolution Field Guidelines: - At least one of resolution_steps, resolution_code, or resolution_notes should be present for the guide entry to be useful. Entries with none of these fields are considered incomplete. - These fields are complementary and can be used together: - resolution_steps: The primary resolution instructions - resolution_code: Supporting code examples - resolution_notes: Additional context or caveats resolution_code: type: string description: |- Example code illustrating how this type of exception was resolved. Serves as a reference when handling similar exceptions in future runs. May require adaptation based on specific context and should not be applied verbatim. resolution_notes: type: string description: |- Additional notes, caveats, or context about the resolution. GitHub Flavored Markdown (GFM) formatted. Use for edge cases, warnings, or supplementary information. kind: type: string description: |- Free-form category used to organize guide entries by origin or type. Caller-provided; the server defaults this to "resolution" when left empty. "resolution" entries are exception resolutions (the historical behavior and the only kind agents produce while resolving an exception). Other values (e.g. "learning") denote general, possibly human-authored guidance that may not be tied to any exception. approver: type: string description: |- Acting user who approved the current version of this guide entry via TransitionGuideEntryState(ACTION_APPROVE). Format: users/{user} Empty when the entry has never been approved. readOnly: true reverted_from: type: string description: |- Semantic version (format: major.minor) this version was reverted from, when this version was produced by RevertGuideEntry. Empty when the version was produced by a create or an ordinary update rather than a revert. Examples: "0.3", "1.0". readOnly: true title: |- The guide entry to update. The guide entry's `name` field is used to identify the entry to update. description: |- The guide entry to update. The guide entry's `name` field is used to identify the entry to update. required: true tags: - Exceptions "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/guideEntries": get: summary: List Guide Entries operationId: ListGuideEntries responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ListGuideEntriesResponse" 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: automation_id in: path required: true schema: type: string - name: page_size description: >- The maximum number of guide entries to return. The service may return fewer than this value. If unspecified, at most 50 guide entries will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. Note: These limits are enforced by server-side validation. in: query required: false schema: type: integer format: int32 - name: page_token description: >- The page token, received from a previous `ListGuideEntries` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `ListGuideEntries` must match the call that provided the page token. in: query required: false schema: type: string - name: show_deleted description: |- If true, soft-deleted guide entries will be included in the results. Deleted entries have delete_time set. Defaults to false (deleted entries are filtered out). in: query required: false schema: type: boolean - name: filter description: >- The filter to apply to the list of guide entries. Follows Google AIP-160 filtering standard (https://google.aip.dev/160). Supported Fields: - title: Guide entry title (partial match only) - resolution_steps: Resolution steps content (partial match only) - resolution_code: Resolution code content (partial match only) - resolution_notes: Resolution notes content (partial match only) - automation: Automation ID (exact match only) - create_time: Guide entry creation timestamp (ISO 8601 format) - update_time: Guide entry update timestamp (ISO 8601 format) - content: (DEPRECATED) Guide entry content - use resolution_steps, resolution_code, or resolution_notes instead Supported Operators: - Comparison: =, !=, <, <=, >, >= - Logical: AND, OR, NOT - Grouping: ( ) - Partial Match: contains Example Filters: - "title contains 'My Guide Entry'" - List guide entries with title containing "My Guide Entry" - "resolution_steps contains 'restart'" - List guide entries with resolution steps containing "restart" - "resolution_code contains 'retry'" - List guide entries with resolution code containing "retry" - "automation = my-automation-id" - List guide entries for a specific automation. Use "-" as the automation_id to list guide entries across all automations in the workspace. - "automation = my-automation-id or automation = another-automation-id" - List guide entries for specific automations. - "create_time > \"2025-01-01T00:00:00Z\"" - Guide entries created after Jan 1, 2025 - "update_time >= \"2025-01-01T00:00:00Z\" AND update_time < \"2025-02-01T00:00:00Z\"" - January 2025 guide entries - "(title contains 'My Guide Entry' OR resolution_steps contains 'error') AND create_time > \"2025-01-01T00:00:00Z\"" - Recent guide entries with specific title or resolution steps in: query required: false schema: type: string tags: - Exceptions post: summary: Create Guide Entry description: |- Creates a TSG entry for an automation. Created by the exception resolver agent during resolution, or directly by users/clients over HTTP to author a learning (kind="learning") that is not tied to a specific exception. operationId: CreateGuideEntry responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1GuideEntry" 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: automation_id in: path required: true schema: type: string - name: user description: |- The acting user, used by the server to attribute the creation of this guide entry. Format: users/{user} Optional: when omitted, the created entry has no creation attribution (the audit column is left NULL). Internal and test callers that do not carry a user identity can omit it. in: query required: false schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/v1GuideEntry" description: The guide entry to create required: true tags: - Exceptions "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents": get: summary: List Agents description: |- Lists all persisted agent IDs. Returns the IDs of agents that have been saved to disk. Agents that exist only in memory (not yet saved) are not included. operationId: ListAgents responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1ListAgentsResponse" 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: Max agents to return; 0 / unset = all in one page. in: query required: false schema: type: integer format: int32 - name: page description: 1-based page number; 0 / unset = page 1. in: query required: false schema: type: integer format: int32 - name: query description: Free-text search over id / name / description; empty = no filter. in: query required: false schema: type: string - name: filter description: |- Optional REL expression over the fields advertised in the response's `filter_schema` (e.g. `generator_kind in ["openai"] && read_only == false`). Empty = no filter. in: query required: false schema: type: string - name: order_by description: |- Sort order, e.g. "name" or "updated_at desc". One of the keys advertised in the schema endpoint's `sort_fields`, optionally followed by "asc" (default) or "desc". Empty = the surface's default order. in: query required: false schema: type: string tags: - Agents post: summary: Create Agent description: |- Creates a new agent with the given name. The agent ID is derived from the name (lowercase, dashed, URL-friendly). operationId: CreateAgent responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1CreateAgentResponse" 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 requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsV1CreateAgentRequest" description: |- Request to create a new agent. The agent is created with an empty template (no generator, no tools, no memory blocks, no variables). The agent is queryable but not runnable until a thread sets the desired configuration as overrides and deploys to produce a new version. required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/hermes/threads": get: summary: List Threads (Hermes, workspace) description: |- Lists all threads for an agent. Targets the built-in `hermes` agent in the workspace scope; the generic form is `ListThreads` on `/agents/{agent_id}`. operationId: HermesListThreads responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1ListThreadsResponse" 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: filter description: |- Optional REL expression filtering over thread fields. Empty = no filter. Supported fields: agent_id (string) status (string, snake_case discriminant) variables., metadata. (string) title, description (optional string) created_at, updated_at (RFC-3339 string literal) agent_version (integer) origin.kind (string: "schedule" / "sub_agent") origin.schedule.schedule_id (string) origin.sub_agent.parent_agent_id (string) origin.sub_agent.parent_thread_id (string) origin.sub_agent.task_id (string) hydration (string: "hydrated" / "dehydrated") Examples: variables.region == "us-east" && updated_at >= "2026-05-01T00:00:00Z" title.contains("invoice") agent_version in [3, 4, 5] origin.kind == "schedule" has(origin.sub_agent.parent_agent_id) in: query required: false schema: type: string tags: - Agents post: summary: Create Thread (Hermes, workspace) description: |- Creates a new thread. The thread_id is auto-generated. Optionally provide a title and description. Targets the built-in `hermes` agent in the workspace scope; the generic form is `CreateThread` on `/agents/{agent_id}`. operationId: HermesCreateThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Thread" 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 requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceCreateThreadBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/hermes/threads/{thread_id}": get: summary: Get Thread (Hermes, workspace) description: |- Gets a thread by ID. Returns thread metadata and event count without loading the full event history. Returns NOT_FOUND if the thread doesn't exist. Targets the built-in `hermes` agent in the workspace scope; the generic form is `GetThread` on `/agents/{agent_id}`. operationId: HermesGetThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Thread" 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: thread_id description: Required. The ID of the thread to retrieve. in: path required: true schema: type: string tags: - Agents patch: summary: Update Thread (Hermes, workspace) description: |- Updates a thread's title and/or description. Targets the built-in `hermes` agent in the workspace scope; the generic form is `UpdateThread` on `/agents/{agent_id}`. operationId: HermesUpdateThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Thread" 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: thread_id description: Required. The ID of the thread to update. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceUpdateThreadBody" required: true tags: - Agents delete: summary: Delete Thread (Hermes, workspace) description: |- Deletes a thread and all its events. Targets the built-in `hermes` agent in the workspace scope; the generic form is `DeleteThread` on `/agents/{agent_id}`. operationId: HermesDeleteThread responses: "204": description: No content. 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: thread_id description: Required. The ID of the thread to delete. in: path required: true schema: type: string tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/hermes/threads/{thread_id}/context": get: summary: Get Thread Context (Hermes, workspace) description: |- Gets thread context information including all context items with token counts. Returns a unified view of all items contributing to the context window: - Memory blocks (fixed and volatile) - Enabled tools (fixed) - Conversation history (compactable) Each item includes its token count for context budget management. Targets the built-in `hermes` agent in the workspace scope; the generic form is `GetThreadContext` on `/agents/{agent_id}`. operationId: HermesGetThreadContext responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1GetThreadContextResponse" 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: thread_id description: The thread ID. in: path required: true schema: type: string tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/hermes/threads/{thread_id}/events": get: summary: Get Thread Events (Hermes, workspace) description: |- Retrieves all events from a thread. This RPC returns the complete history of events for a thread, including user inputs, assistant responses, tool calls, and their results. Events are returned in chronological order. Targets the built-in `hermes` agent in the workspace scope; the generic form is `GetThreadEvents` on `/agents/{agent_id}`. operationId: HermesGetThreadEvents responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1GetEventsResponse" 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: thread_id description: Required. The ID of the thread to retrieve events from. in: path required: true schema: type: string - name: compacted description: |- Optional. If true, return the compacted view of events. The compacted view shows what the LLM sees: events in compacted ranges are excluded and replaced by CompactComplete events containing summaries. If false (default), returns the full event history for UI display. in: query required: false schema: type: boolean - name: include_deleted description: |- Optional. If true, include deleted events in the response. Deleted events will have the `deleted` field set to true on each event. in: query required: false schema: type: boolean tags: - Agents post: summary: Send Message And Wait (Hermes, workspace) description: |- Sends a message and streams back response events synchronously. This RPC adds user input to the specified thread and returns a stream of events representing the assistant's response. Events include output text, tool calls, and completion metadata. Targets the built-in `hermes` agent in the workspace scope; the generic form is `SendMessageAndWait` on `/agents/{agent_id}`. operationId: HermesSendMessageAndWait responses: "200": description: A successful response.(streaming responses) content: application/json: schema: type: object properties: result: $ref: "#/components/schemas/agentsV1Event" error: $ref: "#/components/schemas/rpcStatus" title: Stream result of v1Event 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: thread_id description: Required. The ID of the thread to send the message to. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceSendMessageSyncBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/hermes/threads/{thread_id}/feedback": post: summary: Set Thread Feedback (Hermes, workspace) description: |- Sets feedback (like/dislike) for a generation response. Feedback is mutually exclusive - setting LIKE removes any DISLIKE and vice versa. Setting the same feedback that already exists is a no-op. Use FEEDBACK_TYPE_UNSPECIFIED to clear existing feedback. Feedback is stored with the thread and is purely for analytics/UI purposes. It is not visible to the LLM. Targets the built-in `hermes` agent in the workspace scope; the generic form is `SetThreadFeedback` on `/agents/{agent_id}`. operationId: HermesSetThreadFeedback responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1SetFeedbackResponse" 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: thread_id description: Required. The ID of the thread containing the generation. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceSetFeedbackBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/hermes/threads/{thread_id}/input": post: summary: Send Message (Hermes, workspace) description: |- Sends a message to a thread (fire and forget). The message is added to the thread and generation begins asynchronously. Response events arrive via SubscribeThread stream or SSE, not this RPC. Targets the built-in `hermes` agent in the workspace scope; the generic form is `SendMessage` on `/agents/{agent_id}`. operationId: HermesSendMessage responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1SendMessageResponse" 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: thread_id description: Required. The ID of the thread to send the message to. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceSendMessageBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/hermes/threads/{thread_id}/stream": get: summary: Stream Thread Events (Hermes, workspace) description: |- Subscribe to thread events via SSE Opens a persistent SSE connection that streams all events for the specified thread. **Event Flow:** 1. Historical events are sent first (if the thread has existing events) 2. Live events are streamed as they occur (InputText, OutputText, ToolCall*, etc.) 3. Connection stays open until the client disconnects **SSE Message Format:** Each message contains a JSON-serialized `Event` object in the `data` field: ``` data: {"output_text":{"text":"Hello"}} data: {"generation_complete":{"usage":{"prompt_tokens":10,"completion_tokens":5}}} ``` **Extracting Events:** ```javascript const eventSource = new EventSource('/agents/my-agent/threads/my-thread/stream'); eventSource.onmessage = (e) => { const event = JSON.parse(e.data); if (event.output_text) { console.log('Output:', event.output_text.text); } }; ``` This is the browser-compatible alternative to the gRPC `SubscribeThread` RPC. Targets the built-in `hermes` agent in the workspace scope; the generic form is `StreamThreadEvents` on `/agents/{agent_id}`. operationId: HermesStreamThreadEvents responses: "200": description: SSE stream of thread events content: text/event-stream: schema: type: string description: Server-sent events; each `data:` line is a JSON `agentsV1Event`. "404": description: Agent or thread not found parameters: - name: organization_id in: path required: true schema: type: string - name: workspace_id in: path required: true schema: type: string - name: thread_id in: path description: The ID of the thread to subscribe to. required: true schema: type: string tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/hermes/threads/{thread_id}/sub-agents": get: summary: List Sub Agents (Hermes, workspace) description: |- Lists sub-agents configured for a thread. Targets the built-in `hermes` agent in the workspace scope; the generic form is `ListSubAgents` on `/agents/{agent_id}`. operationId: HermesListSubAgents responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1ListSubAgentsResponse" 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: thread_id description: Required. The thread whose sub-agents to list. in: path required: true schema: type: string tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/hermes/threads/{thread_id}/tool-calls": post: summary: Send Tool Call (Hermes, workspace) description: |- Injects a deterministic tool call into a thread. Appends an assistant-voice preamble announcing the call as an externally requested action, then a synthetic ToolCallStart (plus one ToolCallArgument per supplied argument) to the thread event log under the generation lock, executes the tool through the normal dispatcher, and continues with an LLM turn that has the tool result in context. The preamble keeps the model from misattributing the call to itself. Targets the built-in `hermes` agent in the workspace scope; the generic form is `SendToolCall` on `/agents/{agent_id}`. operationId: HermesSendToolCall responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1SendToolCallResponse" 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: thread_id description: Required. The ID of the thread to inject the call into. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceSendToolCallBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/hermes/threads/{thread_id}/tool-results": post: summary: Send Tool Result (Hermes, workspace) description: |- Sends a tool execution result for a remote tool. Remote tools pause generation when called, waiting for an external system to execute them and return the result via this RPC. Generation resumes once the result is received. Targets the built-in `hermes` agent in the workspace scope; the generic form is `SendToolResult` on `/agents/{agent_id}`. operationId: HermesSendToolResult responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1SendToolResultResponse" 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: thread_id description: Required. The ID of the thread where the remote tool was called. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceSendToolResultBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/hermes/threads/{thread_id}/uploads": post: summary: Upload Thread File (Hermes, workspace) description: |- Upload a file to a thread Accepts a `multipart/form-data` body with a single `file` part and stores it for the thread under `uploads://`. Returns the artifact URI plus the recorded MIME type, byte size, and filename. The MIME type is taken from the part's `Content-Type` header when the browser supplies one, falls back to a guess based on the filename extension, and finally to `application/octet-stream`. Multipart parts other than `file` are accepted and ignored, leaving room for forward-compatible additions (e.g. a content hash, a TTL override) without breaking older servers. **Client example (browser, with progress):** ```javascript const form = new FormData(); form.append('file', file); const xhr = new XMLHttpRequest(); xhr.upload.onprogress = (e) => { if (e.lengthComputable) { console.log(`uploaded ${e.loaded} / ${e.total}`); } }; xhr.onload = () => { if (xhr.status === 200) { const { uri } = JSON.parse(xhr.responseText); // include `uri` in SendMessage.documents } }; xhr.open('POST', `/api/v1/agents/${agentId}/threads/${threadId}/uploads`); xhr.send(form); ``` Targets the built-in `hermes` agent in the workspace scope; the generic form is `UploadThreadFile` on `/agents/{agent_id}`. operationId: HermesUploadThreadFile responses: "200": description: Upload accepted; artifact written to uploads://<filename>. content: application/json: schema: type: object required: - uri - mime_type - size - filename properties: uri: type: string description: Artifact URI to embed in SendMessage.documents. example: uploads://report.pdf mime_type: type: string description: MIME type recorded on the artifact. example: application/pdf size: type: integer format: int64 description: Size of the stored content in bytes. filename: type: string description: Filename the artifact is stored under within the uploads:// store. "400": description: Multipart body missing the `file` part, missing a filename, or otherwise malformed. "404": description: Agent or thread not found. "413": description: Payload too large (server body-size limit exceeded). "500": description: Internal store error. parameters: - name: organization_id in: path required: true schema: type: string - name: workspace_id in: path required: true schema: type: string - name: thread_id in: path description: The ID of the thread the upload is staged into. required: true schema: type: string requestBody: required: true content: multipart/form-data: schema: type: object required: - file properties: file: type: string format: binary description: The file payload. The part's filename and Content-Type are recorded on the artifact. tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/hermes/threads/{thread_id}:compact": post: summary: Compact Thread (Hermes, workspace) description: |- Starts context compaction for a thread. Compaction summarizes conversation history to reduce context size while preserving essential information. This RPC emits a CompactStart event and returns the compact_id for tracking. The actual compaction is performed asynchronously. Once complete, a CompactComplete event with the summary content should be added to the thread using the returned compact_id. While compaction is in progress (CompactStart without CompactComplete), the UI should block user input. Targets the built-in `hermes` agent in the workspace scope; the generic form is `CompactThread` on `/agents/{agent_id}`. operationId: HermesCompactThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1StartCompactionResponse" 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: thread_id description: Required. The ID of the thread to compact. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceStartCompactionBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/hermes/threads/{thread_id}:fork": post: summary: Fork Thread (Hermes, workspace) description: |- Forks (duplicates) a thread with all its data. Creates a new thread that is a complete copy of the source thread, including events, feedback, memory customizations, scratchpad, plan, and template config customizations. Returns FAILED_PRECONDITION if the source thread is currently generating. Targets the built-in `hermes` agent in the workspace scope; the generic form is `ForkThread` on `/agents/{agent_id}`. operationId: HermesForkThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Thread" 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: thread_id description: Required. The source thread to fork. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceForkThreadBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/hermes/threads/{thread_id}:stop": post: summary: Stop Thread (Hermes, workspace) description: |- Stops an in-progress generation in a thread. If a generation is currently running, it will be cancelled and a GenerationFailed event with STOPPED kind will be emitted. If no generation is in progress, this is a no-op and returns stopped=false. Targets the built-in `hermes` agent in the workspace scope; the generic form is `StopThread` on `/agents/{agent_id}`. operationId: HermesStopThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1StopResponse" 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: thread_id description: Required. The ID of the thread with the generation to stop. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceStopBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/hermes/threads/{thread_id}:wake": post: summary: Wake Thread (Hermes, workspace) description: |- Wakes a thread that is currently sleeping (UI "Wake up" button). Atomically ends the pending sleep with `interrupted_by_user = true`, cancels the scheduled wake task, and triggers a new generation so the LLM observes the early return in its rebuilt history. No-op when no sleep is pending; the call still triggers a normal Reminder-driven resume in that case. Targets the built-in `hermes` agent in the workspace scope; the generic form is `WakeThread` on `/agents/{agent_id}`. operationId: HermesWakeThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1WakeResponse" 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: thread_id description: Required. The ID of the sleeping thread to wake. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceWakeBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads": get: summary: List Threads (Smith, workspace) description: |- Lists all threads for an agent. Targets the built-in `smith` agent in the workspace scope; the generic form is `ListThreads` on `/agents/{agent_id}`. operationId: SmithListThreads responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1ListThreadsResponse" 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: filter description: |- Optional REL expression filtering over thread fields. Empty = no filter. Supported fields: agent_id (string) status (string, snake_case discriminant) variables., metadata. (string) title, description (optional string) created_at, updated_at (RFC-3339 string literal) agent_version (integer) origin.kind (string: "schedule" / "sub_agent") origin.schedule.schedule_id (string) origin.sub_agent.parent_agent_id (string) origin.sub_agent.parent_thread_id (string) origin.sub_agent.task_id (string) hydration (string: "hydrated" / "dehydrated") Examples: variables.region == "us-east" && updated_at >= "2026-05-01T00:00:00Z" title.contains("invoice") agent_version in [3, 4, 5] origin.kind == "schedule" has(origin.sub_agent.parent_agent_id) in: query required: false schema: type: string tags: - Agents post: summary: Create Thread (Smith, workspace) description: |- Creates a new thread. The thread_id is auto-generated. Optionally provide a title and description. Targets the built-in `smith` agent in the workspace scope; the generic form is `CreateThread` on `/agents/{agent_id}`. operationId: SmithCreateThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Thread" 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 requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceCreateThreadBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}": get: summary: Get Thread (Smith, workspace) description: |- Gets a thread by ID. Returns thread metadata and event count without loading the full event history. Returns NOT_FOUND if the thread doesn't exist. Targets the built-in `smith` agent in the workspace scope; the generic form is `GetThread` on `/agents/{agent_id}`. operationId: SmithGetThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Thread" 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: thread_id description: Required. The ID of the thread to retrieve. in: path required: true schema: type: string tags: - Agents patch: summary: Update Thread (Smith, workspace) description: |- Updates a thread's title and/or description. Targets the built-in `smith` agent in the workspace scope; the generic form is `UpdateThread` on `/agents/{agent_id}`. operationId: SmithUpdateThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Thread" 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: thread_id description: Required. The ID of the thread to update. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceUpdateThreadBody" required: true tags: - Agents delete: summary: Delete Thread (Smith, workspace) description: |- Deletes a thread and all its events. Targets the built-in `smith` agent in the workspace scope; the generic form is `DeleteThread` on `/agents/{agent_id}`. operationId: SmithDeleteThread responses: "204": description: No content. 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: thread_id description: Required. The ID of the thread to delete. in: path required: true schema: type: string tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}/artifacts": get: summary: List Artifacts (Smith, workspace) description: |- Lists artifacts with optional filters. Supports S3-style delimiter for folder navigation. Thread ID is required for variable-scoped artifact access. Targets the built-in `smith` agent in the workspace scope; the generic form is `ListArtifacts` on `/agents/{agent_id}`. operationId: SmithListArtifacts responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1ListArtifactsResponse" 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: thread_id description: Required. Thread ID for variable-scoped artifact access. in: path required: true schema: type: string - name: prefix description: |- Optional. Filter by URI prefix (e.g., "workspace://src/"). If not specified, lists from all stores. in: query required: false schema: type: string - name: delimiter description: Optional. Delimiter for S3-style folder grouping (typically "/"). in: query required: false schema: type: string - name: mime_type description: Optional. Filter by MIME type prefix (e.g., "text/", "image/"). in: query required: false schema: type: string - name: limit description: Optional. Maximum number of results. in: query required: false schema: type: integer format: int64 tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}/artifacts/{artifact_uri}" : get: summary: Get Artifact (Smith, workspace) description: |- Gets artifact metadata by URI. Targets the built-in `smith` agent in the workspace scope; the generic form is `GetArtifact` on `/agents/{agent_id}`. operationId: SmithGetArtifact responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Artifact" 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: thread_id description: Required. Thread ID for variable-scoped artifact access. in: path required: true schema: type: string - name: artifact_uri description: Required. The artifact URI (e.g., "workspace://src/main.rs"). Percent-encode the URI in the path, for example `workspace%3A%2F%2Fsrc%2Fmain.rs`. in: path required: true schema: type: string tags: - Agents put: summary: Update Artifact (Smith, workspace) description: |- Creates or updates an artifact. Targets the built-in `smith` agent in the workspace scope; the generic form is `UpdateArtifact` on `/agents/{agent_id}`. operationId: SmithUpdateArtifact responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Artifact" 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: thread_id description: Required. Thread ID for variable-scoped artifact access. in: path required: true schema: type: string - name: artifact_uri description: Required. The artifact URI (e.g., "workspace://src/main.rs"). Percent-encode the URI in the path, for example `workspace%3A%2F%2Fsrc%2Fmain.rs`. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceUpdateArtifactBody" required: true tags: - Agents delete: summary: Delete Artifact (Smith, workspace) description: |- Deletes an artifact by URI. Targets the built-in `smith` agent in the workspace scope; the generic form is `DeleteArtifact` on `/agents/{agent_id}`. operationId: SmithDeleteArtifact responses: "204": description: No content. 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: thread_id description: Required. Thread ID for variable-scoped artifact access. in: path required: true schema: type: string - name: artifact_uri description: Required. The artifact URI (e.g., "workspace://src/main.rs"). Percent-encode the URI in the path, for example `workspace%3A%2F%2Fsrc%2Fmain.rs`. in: path required: true schema: type: string tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}/artifacts/{artifact_uri}:content" : get: summary: Get Artifact Content (Smith, workspace) description: |- Gets artifact content by URI. Targets the built-in `smith` agent in the workspace scope; the generic form is `GetArtifactContent` on `/agents/{agent_id}`. operationId: SmithGetArtifactContent responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1ArtifactContentResponse" 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: thread_id description: Required. Thread ID for variable-scoped artifact access. in: path required: true schema: type: string - name: artifact_uri description: Required. The artifact URI (e.g., "workspace://src/main.rs"). Percent-encode the URI in the path, for example `workspace%3A%2F%2Fsrc%2Fmain.rs`. in: path required: true schema: type: string tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}/artifacts/{artifact_uri}:diff" : get: summary: Get Artifact Diff (Smith, workspace) description: |- Gets the diff for a single staged artifact. Returns the unified diff for a specific artifact if it has staged changes. Returns empty diff for binary files or if no changes exist. Targets the built-in `smith` agent in the workspace scope; the generic form is `GetArtifactDiff` on `/agents/{agent_id}`. operationId: SmithGetArtifactDiff responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1GetArtifactDiffResponse" 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: thread_id description: Required. Thread ID for variable-scoped artifact access. in: path required: true schema: type: string - name: artifact_uri description: Required. The artifact URI (e.g., "workspace://src/main.rs"). Percent-encode the URI in the path, for example `workspace%3A%2F%2Fsrc%2Fmain.rs`. in: path required: true schema: type: string tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}/artifacts:commit": post: summary: Commit Artifacts (Smith, workspace) description: |- Commits staged artifact changes to the underlying store. Persists all staged changes (additions, modifications, deletions) to the underlying store. For stores without staging, this is a no-op. Targets the built-in `smith` agent in the workspace scope; the generic form is `CommitArtifacts` on `/agents/{agent_id}`. operationId: SmithCommitArtifacts responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1CommitArtifactsResponse" 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: thread_id description: Required. Thread ID for variable-scoped artifact access. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceCommitArtifactsBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}/artifacts:diff": post: summary: Diff Artifacts (Smith, workspace) description: |- Gets staged artifact changes with optional diff content. Returns information about artifacts that have been modified but not yet committed. For stores with staging enabled, this shows pending changes. For stores without staging, returns an empty response. Targets the built-in `smith` agent in the workspace scope; the generic form is `DiffArtifacts` on `/agents/{agent_id}`. operationId: SmithDiffArtifacts responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1DiffArtifactsResponse" 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: thread_id description: Required. Thread ID for variable-scoped artifact access. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceDiffArtifactsBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}/artifacts:discard": post: summary: Discard Artifacts (Smith, workspace) description: |- Discards all staged artifact changes without committing. Clears all pending changes (additions, modifications, deletions) from the staging area. For stores without staging, this is a no-op. Targets the built-in `smith` agent in the workspace scope; the generic form is `DiscardArtifacts` on `/agents/{agent_id}`. operationId: SmithDiscardArtifacts responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1DiscardArtifactsResponse" 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: thread_id description: Required. Thread ID for variable-scoped artifact access. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceDiscardArtifactsBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}/artifacts:grep": post: summary: Grep Artifacts (Smith, workspace) description: |- Searches artifact contents using regex pattern matching. Targets the built-in `smith` agent in the workspace scope; the generic form is `GrepArtifacts` on `/agents/{agent_id}`. operationId: SmithGrepArtifacts responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1GrepArtifactsResponse" 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: thread_id description: Required. Thread ID for variable-scoped artifact access. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceGrepArtifactsBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}/artifacts:staging": get: summary: Get Artifacts Staging Summary (Smith, workspace) description: |- Gets a summary of staged artifact changes. Returns a lightweight summary of pending changes including counts and change metadata without diff content. Use DiffArtifacts for full diffs. Targets the built-in `smith` agent in the workspace scope; the generic form is `GetArtifactsStagingSummary` on `/agents/{agent_id}`. operationId: SmithGetArtifactsStagingSummary responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1GetArtifactsStagingSummaryResponse" 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: thread_id description: Required. Thread ID for variable-scoped artifact access. in: path required: true schema: type: string - name: prefix description: |- Optional. Store prefix to limit summary scope (e.g., "workspace://"). If not specified, returns summary for all stores. in: query required: false schema: type: string tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}/context": get: summary: Get Thread Context (Smith, workspace) description: |- Gets thread context information including all context items with token counts. Returns a unified view of all items contributing to the context window: - Memory blocks (fixed and volatile) - Enabled tools (fixed) - Conversation history (compactable) Each item includes its token count for context budget management. Targets the built-in `smith` agent in the workspace scope; the generic form is `GetThreadContext` on `/agents/{agent_id}`. operationId: SmithGetThreadContext responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1GetThreadContextResponse" 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: thread_id description: The thread ID. in: path required: true schema: type: string tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}/events": get: summary: Get Thread Events (Smith, workspace) description: |- Retrieves all events from a thread. This RPC returns the complete history of events for a thread, including user inputs, assistant responses, tool calls, and their results. Events are returned in chronological order. Targets the built-in `smith` agent in the workspace scope; the generic form is `GetThreadEvents` on `/agents/{agent_id}`. operationId: SmithGetThreadEvents responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1GetEventsResponse" 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: thread_id description: Required. The ID of the thread to retrieve events from. in: path required: true schema: type: string - name: compacted description: |- Optional. If true, return the compacted view of events. The compacted view shows what the LLM sees: events in compacted ranges are excluded and replaced by CompactComplete events containing summaries. If false (default), returns the full event history for UI display. in: query required: false schema: type: boolean - name: include_deleted description: |- Optional. If true, include deleted events in the response. Deleted events will have the `deleted` field set to true on each event. in: query required: false schema: type: boolean tags: - Agents post: summary: Send Message And Wait (Smith, workspace) description: |- Sends a message and streams back response events synchronously. This RPC adds user input to the specified thread and returns a stream of events representing the assistant's response. Events include output text, tool calls, and completion metadata. Targets the built-in `smith` agent in the workspace scope; the generic form is `SendMessageAndWait` on `/agents/{agent_id}`. operationId: SmithSendMessageAndWait responses: "200": description: A successful response.(streaming responses) content: application/json: schema: type: object properties: result: $ref: "#/components/schemas/agentsV1Event" error: $ref: "#/components/schemas/rpcStatus" title: Stream result of v1Event 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: thread_id description: Required. The ID of the thread to send the message to. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceSendMessageSyncBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}/feedback": post: summary: Set Thread Feedback (Smith, workspace) description: |- Sets feedback (like/dislike) for a generation response. Feedback is mutually exclusive - setting LIKE removes any DISLIKE and vice versa. Setting the same feedback that already exists is a no-op. Use FEEDBACK_TYPE_UNSPECIFIED to clear existing feedback. Feedback is stored with the thread and is purely for analytics/UI purposes. It is not visible to the LLM. Targets the built-in `smith` agent in the workspace scope; the generic form is `SetThreadFeedback` on `/agents/{agent_id}`. operationId: SmithSetThreadFeedback responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1SetFeedbackResponse" 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: thread_id description: Required. The ID of the thread containing the generation. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceSetFeedbackBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}/input": post: summary: Send Message (Smith, workspace) description: |- Sends a message to a thread (fire and forget). The message is added to the thread and generation begins asynchronously. Response events arrive via SubscribeThread stream or SSE, not this RPC. Targets the built-in `smith` agent in the workspace scope; the generic form is `SendMessage` on `/agents/{agent_id}`. operationId: SmithSendMessage responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1SendMessageResponse" 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: thread_id description: Required. The ID of the thread to send the message to. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceSendMessageBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}/plan/active": get: summary: Get Active Plan (Smith, workspace) description: |- Gets the active plan snapshot for a thread (with per-step statuses). Distinct from `GET /plan`, which returns the template. Returns NOT_FOUND if no active plan exists. Targets the built-in `smith` agent in the workspace scope; the generic form is `GetActivePlan` on `/agents/{agent_id}`. operationId: SmithGetActivePlan responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Plan" 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: thread_id description: Required. The ID of the thread to get the plan for. in: path required: true schema: type: string tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}/plan/active/phases/{phase_index}/steps/{step_index}:mark" : post: summary: Mark Plan Step (Smith, workspace) description: |- Marks a step on the active plan as completed or failed. Returns NOT_FOUND if no active plan exists or the phase/step index is invalid. Returns FAILED_PRECONDITION if the thread is currently generating, the step is not in the active phase, or the step is already resolved. Targets the built-in `smith` agent in the workspace scope; the generic form is `MarkPlanStep` on `/agents/{agent_id}`. operationId: SmithMarkPlanStep responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Plan" 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: thread_id description: Required. The ID of the thread whose plan to modify. in: path required: true schema: type: string - name: phase_index description: Required. 1-indexed phase position. in: path required: true schema: type: integer format: int64 - name: step_index description: Required. 1-indexed step position. in: path required: true schema: type: integer format: int64 requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceMarkStepBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}/plan/active:deactivate": post: summary: Deactivate Plan (Smith, workspace) description: |- Deactivates the active plan. The snapshot is kept (flagged inactive) for status carry-over on the next activation. No generation guard — always allowed. Returns NOT_FOUND if no active plan exists. Returns FAILED_PRECONDITION if the plan is not active. Targets the built-in `smith` agent in the workspace scope; the generic form is `DeactivatePlan` on `/agents/{agent_id}`. operationId: SmithDeactivatePlan responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Plan" 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: thread_id description: Required. The ID of the thread whose plan to deactivate. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceDeactivatePlanBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}/plan/active:reset": post: summary: Reset Plan (Smith, workspace) description: |- Resets all step statuses on the active plan back to pending. Clears all step statuses and failure reasons. If the plan is active, it is deactivated first before resetting. Returns NOT_FOUND if no active plan exists. Returns FAILED_PRECONDITION if the thread is currently generating. Targets the built-in `smith` agent in the workspace scope; the generic form is `ResetPlan` on `/agents/{agent_id}`. operationId: SmithResetPlan responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Plan" 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: thread_id description: Required. The ID of the thread whose plan to reset. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceResetPlanBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}/plan:activate": post: summary: Activate Plan (Smith, workspace) description: |- Activates the plan for a thread. Snapshots the current template plan and carries over statuses from any previous snapshot by id. Returns NOT_FOUND if no plan template exists. Returns FAILED_PRECONDITION if the thread is currently generating, the plan is already active, or the template has no phases. Targets the built-in `smith` agent in the workspace scope; the generic form is `ActivatePlan` on `/agents/{agent_id}`. operationId: SmithActivatePlan responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Plan" 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: thread_id description: Required. The ID of the thread whose plan to activate. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceActivatePlanBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}/stream": get: summary: Stream Thread Events (Smith, workspace) description: |- Subscribe to thread events via SSE Opens a persistent SSE connection that streams all events for the specified thread. **Event Flow:** 1. Historical events are sent first (if the thread has existing events) 2. Live events are streamed as they occur (InputText, OutputText, ToolCall*, etc.) 3. Connection stays open until the client disconnects **SSE Message Format:** Each message contains a JSON-serialized `Event` object in the `data` field: ``` data: {"output_text":{"text":"Hello"}} data: {"generation_complete":{"usage":{"prompt_tokens":10,"completion_tokens":5}}} ``` **Extracting Events:** ```javascript const eventSource = new EventSource('/agents/my-agent/threads/my-thread/stream'); eventSource.onmessage = (e) => { const event = JSON.parse(e.data); if (event.output_text) { console.log('Output:', event.output_text.text); } }; ``` This is the browser-compatible alternative to the gRPC `SubscribeThread` RPC. Targets the built-in `smith` agent in the workspace scope; the generic form is `StreamThreadEvents` on `/agents/{agent_id}`. operationId: SmithStreamThreadEvents responses: "200": description: SSE stream of thread events content: text/event-stream: schema: type: string description: Server-sent events; each `data:` line is a JSON `agentsV1Event`. "404": description: Agent or thread not found parameters: - name: organization_id in: path required: true schema: type: string - name: workspace_id in: path required: true schema: type: string - name: thread_id in: path description: The ID of the thread to subscribe to. required: true schema: type: string tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}/sub-agents": get: summary: List Sub Agents (Smith, workspace) description: |- Lists sub-agents configured for a thread. Targets the built-in `smith` agent in the workspace scope; the generic form is `ListSubAgents` on `/agents/{agent_id}`. operationId: SmithListSubAgents responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1ListSubAgentsResponse" 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: thread_id description: Required. The thread whose sub-agents to list. in: path required: true schema: type: string tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}/tool-calls": post: summary: Send Tool Call (Smith, workspace) description: |- Injects a deterministic tool call into a thread. Appends an assistant-voice preamble announcing the call as an externally requested action, then a synthetic ToolCallStart (plus one ToolCallArgument per supplied argument) to the thread event log under the generation lock, executes the tool through the normal dispatcher, and continues with an LLM turn that has the tool result in context. The preamble keeps the model from misattributing the call to itself. Targets the built-in `smith` agent in the workspace scope; the generic form is `SendToolCall` on `/agents/{agent_id}`. operationId: SmithSendToolCall responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1SendToolCallResponse" 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: thread_id description: Required. The ID of the thread to inject the call into. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceSendToolCallBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}/tool-results": post: summary: Send Tool Result (Smith, workspace) description: |- Sends a tool execution result for a remote tool. Remote tools pause generation when called, waiting for an external system to execute them and return the result via this RPC. Generation resumes once the result is received. Targets the built-in `smith` agent in the workspace scope; the generic form is `SendToolResult` on `/agents/{agent_id}`. operationId: SmithSendToolResult responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1SendToolResultResponse" 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: thread_id description: Required. The ID of the thread where the remote tool was called. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceSendToolResultBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}/uploads": post: summary: Upload Thread File (Smith, workspace) description: |- Upload a file to a thread Accepts a `multipart/form-data` body with a single `file` part and stores it for the thread under `uploads://`. Returns the artifact URI plus the recorded MIME type, byte size, and filename. The MIME type is taken from the part's `Content-Type` header when the browser supplies one, falls back to a guess based on the filename extension, and finally to `application/octet-stream`. Multipart parts other than `file` are accepted and ignored, leaving room for forward-compatible additions (e.g. a content hash, a TTL override) without breaking older servers. **Client example (browser, with progress):** ```javascript const form = new FormData(); form.append('file', file); const xhr = new XMLHttpRequest(); xhr.upload.onprogress = (e) => { if (e.lengthComputable) { console.log(`uploaded ${e.loaded} / ${e.total}`); } }; xhr.onload = () => { if (xhr.status === 200) { const { uri } = JSON.parse(xhr.responseText); // include `uri` in SendMessage.documents } }; xhr.open('POST', `/api/v1/agents/${agentId}/threads/${threadId}/uploads`); xhr.send(form); ``` Targets the built-in `smith` agent in the workspace scope; the generic form is `UploadThreadFile` on `/agents/{agent_id}`. operationId: SmithUploadThreadFile responses: "200": description: Upload accepted; artifact written to uploads://<filename>. content: application/json: schema: type: object required: - uri - mime_type - size - filename properties: uri: type: string description: Artifact URI to embed in SendMessage.documents. example: uploads://report.pdf mime_type: type: string description: MIME type recorded on the artifact. example: application/pdf size: type: integer format: int64 description: Size of the stored content in bytes. filename: type: string description: Filename the artifact is stored under within the uploads:// store. "400": description: Multipart body missing the `file` part, missing a filename, or otherwise malformed. "404": description: Agent or thread not found. "413": description: Payload too large (server body-size limit exceeded). "500": description: Internal store error. parameters: - name: organization_id in: path required: true schema: type: string - name: workspace_id in: path required: true schema: type: string - name: thread_id in: path description: The ID of the thread the upload is staged into. required: true schema: type: string requestBody: required: true content: multipart/form-data: schema: type: object required: - file properties: file: type: string format: binary description: The file payload. The part's filename and Content-Type are recorded on the artifact. tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}:compact": post: summary: Compact Thread (Smith, workspace) description: |- Starts context compaction for a thread. Compaction summarizes conversation history to reduce context size while preserving essential information. This RPC emits a CompactStart event and returns the compact_id for tracking. The actual compaction is performed asynchronously. Once complete, a CompactComplete event with the summary content should be added to the thread using the returned compact_id. While compaction is in progress (CompactStart without CompactComplete), the UI should block user input. Targets the built-in `smith` agent in the workspace scope; the generic form is `CompactThread` on `/agents/{agent_id}`. operationId: SmithCompactThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1StartCompactionResponse" 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: thread_id description: Required. The ID of the thread to compact. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceStartCompactionBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}:fork": post: summary: Fork Thread (Smith, workspace) description: |- Forks (duplicates) a thread with all its data. Creates a new thread that is a complete copy of the source thread, including events, feedback, memory customizations, scratchpad, plan, and template config customizations. Returns FAILED_PRECONDITION if the source thread is currently generating. Targets the built-in `smith` agent in the workspace scope; the generic form is `ForkThread` on `/agents/{agent_id}`. operationId: SmithForkThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Thread" 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: thread_id description: Required. The source thread to fork. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceForkThreadBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}:stop": post: summary: Stop Thread (Smith, workspace) description: |- Stops an in-progress generation in a thread. If a generation is currently running, it will be cancelled and a GenerationFailed event with STOPPED kind will be emitted. If no generation is in progress, this is a no-op and returns stopped=false. Targets the built-in `smith` agent in the workspace scope; the generic form is `StopThread` on `/agents/{agent_id}`. operationId: SmithStopThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1StopResponse" 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: thread_id description: Required. The ID of the thread with the generation to stop. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceStopBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}:wake": post: summary: Wake Thread (Smith, workspace) description: |- Wakes a thread that is currently sleeping (UI "Wake up" button). Atomically ends the pending sleep with `interrupted_by_user = true`, cancels the scheduled wake task, and triggers a new generation so the LLM observes the early return in its rebuilt history. No-op when no sleep is pending; the call still triggers a normal Reminder-driven resume in that case. Targets the built-in `smith` agent in the workspace scope; the generic form is `WakeThread` on `/agents/{agent_id}`. operationId: SmithWakeThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1WakeResponse" 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: thread_id description: Required. The ID of the sleeping thread to wake. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceWakeBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}": get: summary: Get Agent description: |- Gets an agent's metadata. Returns the agent's ID and display name. Use other service methods to get detailed information like memory blocks. operationId: GetAgent responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1GetAgentResponse" 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: agent_id description: Required. The ID of the agent to get. in: path required: true schema: type: string tags: - Agents patch: summary: Update Agent description: |- Updates an agent's metadata. Supports updating the display name and the label set. operationId: UpdateAgent responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1UpdateAgentResponse" 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: agent_id description: Required. The ID of the agent to update. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsAgentServiceUpdateAgentBody" required: true tags: - Agents delete: summary: Delete Agent description: |- Deletes an agent from both memory and disk. This removes the agent completely. The operation cannot be undone. operationId: DeleteAgent responses: "204": description: No content. 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: agent_id description: Required. The ID of the agent to delete. in: path required: true schema: type: string tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/tags/{tag}": get: summary: Get Agent Version By Tag description: Fetches a specific version of an agent's full configuration by tag name. operationId: GetAgentVersionByTag responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1GetAgentResponse" 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: agent_id description: Required. The agent ID. in: path required: true schema: type: string - name: tag description: Required. The tag name resolving to a version. in: path required: true schema: type: string tags: - Agents delete: summary: Untag Agent Version description: Removes a tag from an agent. operationId: UntagAgentVersion responses: "204": description: No content. 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: agent_id description: The agent ID. in: path required: true schema: type: string - name: tag description: The tag name to remove. in: path required: true schema: type: string tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads": get: summary: List Threads description: Lists all threads for an agent. operationId: ListThreads responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1ListThreadsResponse" 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: agent_id description: Required. The ID of the agent whose threads to list. in: path required: true schema: type: string - name: filter description: |- Optional REL expression filtering over thread fields. Empty = no filter. Supported fields: agent_id (string) status (string, snake_case discriminant) variables., metadata. (string) title, description (optional string) created_at, updated_at (RFC-3339 string literal) agent_version (integer) origin.kind (string: "schedule" / "sub_agent") origin.schedule.schedule_id (string) origin.sub_agent.parent_agent_id (string) origin.sub_agent.parent_thread_id (string) origin.sub_agent.task_id (string) hydration (string: "hydrated" / "dehydrated") Examples: variables.region == "us-east" && updated_at >= "2026-05-01T00:00:00Z" title.contains("invoice") agent_version in [3, 4, 5] origin.kind == "schedule" has(origin.sub_agent.parent_agent_id) in: query required: false schema: type: string tags: - Agents post: summary: Create Thread description: |- Creates a new thread. The thread_id is auto-generated. Optionally provide a title and description. operationId: CreateThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Thread" 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: agent_id description: Required. The ID of the agent to create the thread for. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceCreateThreadBody" required: true tags: - Agents delete: summary: Delete All Threads description: Deletes all threads for an agent. operationId: DeleteAllThreads responses: "204": description: No content. 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: agent_id description: Required. The ID of the agent whose threads to delete. in: path required: true schema: type: string tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}": get: summary: Get Thread description: |- Gets a thread by ID. Returns thread metadata and event count without loading the full event history. Returns NOT_FOUND if the thread doesn't exist. operationId: GetThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Thread" 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: agent_id description: Required. The ID of the agent that owns the thread. in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to retrieve. in: path required: true schema: type: string tags: - Agents patch: summary: Update Thread description: Updates a thread's title and/or description. operationId: UpdateThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Thread" 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: agent_id description: Required. The ID of the agent that owns the thread. in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to update. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceUpdateThreadBody" required: true tags: - Agents delete: summary: Delete Thread description: Deletes a thread and all its events. operationId: DeleteThread responses: "204": description: No content. 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: agent_id description: Required. The ID of the agent that owns the thread. in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to delete. in: path required: true schema: type: string tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/artifacts": get: summary: List Artifacts description: |- Lists artifacts with optional filters. Supports S3-style delimiter for folder navigation. Thread ID is required for variable-scoped artifact access. operationId: ListArtifacts responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1ListArtifactsResponse" 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: agent_id description: Required. The agent ID. in: path required: true schema: type: string - name: thread_id description: Required. Thread ID for variable-scoped artifact access. in: path required: true schema: type: string - name: prefix description: |- Optional. Filter by URI prefix (e.g., "workspace://src/"). If not specified, lists from all stores. in: query required: false schema: type: string - name: delimiter description: Optional. Delimiter for S3-style folder grouping (typically "/"). in: query required: false schema: type: string - name: mime_type description: Optional. Filter by MIME type prefix (e.g., "text/", "image/"). in: query required: false schema: type: string - name: limit description: Optional. Maximum number of results. in: query required: false schema: type: integer format: int64 tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/artifacts/{artifact_uri}" : get: summary: Get Artifact description: Gets artifact metadata by URI. operationId: GetArtifact responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Artifact" 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: agent_id description: Required. The agent ID. in: path required: true schema: type: string - name: thread_id description: Required. Thread ID for variable-scoped artifact access. in: path required: true schema: type: string - name: artifact_uri description: Required. The artifact URI (e.g., "workspace://src/main.rs"). Percent-encode the URI in the path, for example `workspace%3A%2F%2Fsrc%2Fmain.rs`. in: path required: true schema: type: string tags: - Agents put: summary: Update Artifact description: Creates or updates an artifact. operationId: UpdateArtifact responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Artifact" 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: agent_id description: Required. The agent ID. in: path required: true schema: type: string - name: thread_id description: Required. Thread ID for variable-scoped artifact access. in: path required: true schema: type: string - name: artifact_uri description: Required. The artifact URI (e.g., "workspace://src/main.rs"). Percent-encode the URI in the path, for example `workspace%3A%2F%2Fsrc%2Fmain.rs`. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceUpdateArtifactBody" required: true tags: - Agents delete: summary: Delete Artifact description: Deletes an artifact by URI. operationId: DeleteArtifact responses: "204": description: No content. 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: agent_id description: Required. The agent ID. in: path required: true schema: type: string - name: thread_id description: Required. Thread ID for variable-scoped artifact access. in: path required: true schema: type: string - name: artifact_uri description: Required. The artifact URI (e.g., "workspace://src/main.rs"). Percent-encode the URI in the path, for example `workspace%3A%2F%2Fsrc%2Fmain.rs`. in: path required: true schema: type: string tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/artifacts/{artifact_uri}:content" : get: summary: Get Artifact Content description: Gets artifact content by URI. operationId: GetArtifactContent responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1ArtifactContentResponse" 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: agent_id description: Required. The agent ID. in: path required: true schema: type: string - name: thread_id description: Required. Thread ID for variable-scoped artifact access. in: path required: true schema: type: string - name: artifact_uri description: Required. The artifact URI (e.g., "workspace://src/main.rs"). Percent-encode the URI in the path, for example `workspace%3A%2F%2Fsrc%2Fmain.rs`. in: path required: true schema: type: string tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/artifacts/{artifact_uri}:diff" : get: summary: Get Artifact Diff description: |- Gets the diff for a single staged artifact. Returns the unified diff for a specific artifact if it has staged changes. Returns empty diff for binary files or if no changes exist. operationId: GetArtifactDiff responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1GetArtifactDiffResponse" 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: agent_id description: Required. The agent ID. in: path required: true schema: type: string - name: thread_id description: Required. Thread ID for variable-scoped artifact access. in: path required: true schema: type: string - name: artifact_uri description: Required. The artifact URI (e.g., "workspace://src/main.rs"). Percent-encode the URI in the path, for example `workspace%3A%2F%2Fsrc%2Fmain.rs`. in: path required: true schema: type: string tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/artifacts/{artifact_uri}:thumbnail" : get: summary: Get Artifact Thumbnail description: |- Fetch a server-rendered thumbnail of an artifact Returns a rendered preview image for the artifact at `artifact_uri`. The first request renders the image; subsequent requests for identical artifact bytes serve from a thread-scoped cache. Returns `404` when the artifact does not exist or the file type has no preview support — clients should fall back to a generic file-type icon. Returns `500` when rendering failed. operationId: GetArtifactThumbnail responses: "200": description: Rendered thumbnail bytes. headers: ETag: description: Strong validator derived from `sha256(artifact bytes) + size`. schema: type: string Cache-Control: description: Always `public, max-age=31536000, immutable` since thumbnails are content-addressed. schema: type: string content: image/png: schema: type: string format: binary image/jpeg: schema: type: string format: binary "304": description: Cached body matches `If-None-Match` — no body returned. "400": description: Invalid `size` parameter. "404": description: Artifact missing or file type has no preview support — client should fall back to a generic icon. "500": description: Thumbnail render or store error. parameters: - name: organization_id in: path required: true schema: type: string - name: workspace_id in: path required: true schema: type: string - name: agent_id in: path description: The ID of the agent that owns the thread. required: true schema: type: string - name: thread_id in: path description: The ID of the thread the artifact belongs to. required: true schema: type: string - name: artifact_uri in: path description: |- The artifact URI (e.g. `uploads://report.pdf`, `workspace://src/main.rs`). Must be URL-encoded so the `://` and any embedded slashes survive routing as a single path segment. Percent-encode the URI in the path, for example `workspace%3A%2F%2Fsrc%2Fmain.rs`. required: true schema: type: string - name: size in: query description: Logical size bucket — `small` (~140 px) or `medium` (~320 px). Defaults to `small`. required: false schema: type: string enum: - small - medium default: small - name: If-None-Match in: header description: Conditional GET. When the ETag matches the cached thumbnail, the server responds `304 Not Modified` with no body. required: false schema: type: string tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/artifacts:commit": post: summary: Commit Artifacts description: |- Commits staged artifact changes to the underlying store. Persists all staged changes (additions, modifications, deletions) to the underlying store. For stores without staging, this is a no-op. operationId: CommitArtifacts responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1CommitArtifactsResponse" 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: agent_id description: Required. The agent ID. in: path required: true schema: type: string - name: thread_id description: Required. Thread ID for variable-scoped artifact access. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceCommitArtifactsBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/artifacts:diff": post: summary: Diff Artifacts description: |- Gets staged artifact changes with optional diff content. Returns information about artifacts that have been modified but not yet committed. For stores with staging enabled, this shows pending changes. For stores without staging, returns an empty response. operationId: DiffArtifacts responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1DiffArtifactsResponse" 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: agent_id description: Required. The agent ID. in: path required: true schema: type: string - name: thread_id description: Required. Thread ID for variable-scoped artifact access. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceDiffArtifactsBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/artifacts:discard": post: summary: Discard Artifacts description: |- Discards all staged artifact changes without committing. Clears all pending changes (additions, modifications, deletions) from the staging area. For stores without staging, this is a no-op. operationId: DiscardArtifacts responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1DiscardArtifactsResponse" 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: agent_id description: Required. The agent ID. in: path required: true schema: type: string - name: thread_id description: Required. Thread ID for variable-scoped artifact access. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceDiscardArtifactsBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/artifacts:grep": post: summary: Grep Artifacts description: Searches artifact contents using regex pattern matching. operationId: GrepArtifacts responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1GrepArtifactsResponse" 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: agent_id description: Required. The agent ID. in: path required: true schema: type: string - name: thread_id description: Required. Thread ID for variable-scoped artifact access. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceGrepArtifactsBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/artifacts:staging": get: summary: Get Artifacts Staging Summary description: |- Gets a summary of staged artifact changes. Returns a lightweight summary of pending changes including counts and change metadata without diff content. Use DiffArtifacts for full diffs. operationId: GetArtifactsStagingSummary responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1GetArtifactsStagingSummaryResponse" 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: agent_id description: Required. The agent ID. in: path required: true schema: type: string - name: thread_id description: Required. Thread ID for variable-scoped artifact access. in: path required: true schema: type: string - name: prefix description: |- Optional. Store prefix to limit summary scope (e.g., "workspace://"). If not specified, returns summary for all stores. in: query required: false schema: type: string tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/context": get: summary: Get Thread Context description: |- Gets thread context information including all context items with token counts. Returns a unified view of all items contributing to the context window: - Memory blocks (fixed and volatile) - Enabled tools (fixed) - Conversation history (compactable) Each item includes its token count for context budget management. operationId: GetThreadContext responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1GetThreadContextResponse" 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: agent_id description: The agent ID. in: path required: true schema: type: string - name: thread_id description: The thread ID. in: path required: true schema: type: string tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/events": get: summary: Get Thread Events description: |- Retrieves all events from a thread. This RPC returns the complete history of events for a thread, including user inputs, assistant responses, tool calls, and their results. Events are returned in chronological order. operationId: GetThreadEvents responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1GetEventsResponse" 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: agent_id description: Required. The ID of the agent that owns the thread. in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to retrieve events from. in: path required: true schema: type: string - name: compacted description: |- Optional. If true, return the compacted view of events. The compacted view shows what the LLM sees: events in compacted ranges are excluded and replaced by CompactComplete events containing summaries. If false (default), returns the full event history for UI display. in: query required: false schema: type: boolean - name: include_deleted description: |- Optional. If true, include deleted events in the response. Deleted events will have the `deleted` field set to true on each event. in: query required: false schema: type: boolean tags: - Agents post: summary: Send Message And Wait description: |- Sends a message and streams back response events synchronously. This RPC adds user input to the specified thread and returns a stream of events representing the assistant's response. Events include output text, tool calls, and completion metadata. operationId: SendMessageAndWait responses: "200": description: A successful response.(streaming responses) content: application/json: schema: type: object properties: result: $ref: "#/components/schemas/agentsV1Event" error: $ref: "#/components/schemas/rpcStatus" title: Stream result of v1Event 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: agent_id description: Required. The ID of the agent that owns the thread. in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to send the message to. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceSendMessageSyncBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/events:delete": post: summary: Delete Event description: Deletes an event and its entire associated turn from the thread. operationId: DeleteEvent responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1DeleteEventResponse" 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: agent_id in: path required: true schema: type: string - name: thread_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceDeleteEventBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/events:reset": post: summary: Reset Events description: |- Resets all events and feedback in a thread. Clears the entire event history and associated feedback while preserving all other thread state (plan, memory customizations, config customizations, scratchpad). Returns FAILED_PRECONDITION if the thread is currently generating. operationId: ResetEvents responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1ResetEventsResponse" 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: agent_id description: Required. The agent that owns the thread. in: path required: true schema: type: string - name: thread_id description: Required. The thread whose events to reset. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceResetEventsBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/events:restore": post: summary: Restore Event description: Restores a previously deleted event and its entire associated turn. operationId: RestoreEvent responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1RestoreEventResponse" 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: agent_id in: path required: true schema: type: string - name: thread_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceRestoreEventBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/feedback": post: summary: Set Thread Feedback description: |- Sets feedback (like/dislike) for a generation response. Feedback is mutually exclusive - setting LIKE removes any DISLIKE and vice versa. Setting the same feedback that already exists is a no-op. Use FEEDBACK_TYPE_UNSPECIFIED to clear existing feedback. Feedback is stored with the thread and is purely for analytics/UI purposes. It is not visible to the LLM. operationId: SetThreadFeedback responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1SetFeedbackResponse" 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: agent_id description: Required. The ID of the agent that owns the thread. in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread containing the generation. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceSetFeedbackBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/input": post: summary: Send Message description: |- Sends a message to a thread (fire and forget). The message is added to the thread and generation begins asynchronously. Response events arrive via SubscribeThread stream or SSE, not this RPC. operationId: SendMessage responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1SendMessageResponse" 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: agent_id description: Required. The ID of the agent that owns the thread. in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to send the message to. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceSendMessageBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/plan/active": get: summary: Get Active Plan description: |- Gets the active plan snapshot for a thread (with per-step statuses). Distinct from `GET /plan`, which returns the template. Returns NOT_FOUND if no active plan exists. operationId: GetActivePlan responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Plan" 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: agent_id description: Required. The ID of the agent that owns the thread. in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to get the plan for. in: path required: true schema: type: string tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/plan/active/phases/{phase_index}/steps/{step_index}:mark" : post: summary: Mark Plan Step description: |- Marks a step on the active plan as completed or failed. Returns NOT_FOUND if no active plan exists or the phase/step index is invalid. Returns FAILED_PRECONDITION if the thread is currently generating, the step is not in the active phase, or the step is already resolved. operationId: MarkPlanStep responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Plan" 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: agent_id description: Required. The ID of the agent that owns the thread. in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread whose plan to modify. in: path required: true schema: type: string - name: phase_index description: Required. 1-indexed phase position. in: path required: true schema: type: integer format: int64 - name: step_index description: Required. 1-indexed step position. in: path required: true schema: type: integer format: int64 requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceMarkStepBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/plan/active:deactivate" : post: summary: Deactivate Plan description: |- Deactivates the active plan. The snapshot is kept (flagged inactive) for status carry-over on the next activation. No generation guard — always allowed. Returns NOT_FOUND if no active plan exists. Returns FAILED_PRECONDITION if the plan is not active. operationId: DeactivatePlan responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Plan" 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: agent_id description: Required. The ID of the agent that owns the thread. in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread whose plan to deactivate. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceDeactivatePlanBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/plan/active:reset": post: summary: Reset Plan description: |- Resets all step statuses on the active plan back to pending. Clears all step statuses and failure reasons. If the plan is active, it is deactivated first before resetting. Returns NOT_FOUND if no active plan exists. Returns FAILED_PRECONDITION if the thread is currently generating. operationId: ResetPlan responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Plan" 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: agent_id description: Required. The ID of the agent that owns the thread. in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread whose plan to reset. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceResetPlanBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/plan:activate": post: summary: Activate Plan description: |- Activates the plan for a thread. Snapshots the current template plan and carries over statuses from any previous snapshot by id. Returns NOT_FOUND if no plan template exists. Returns FAILED_PRECONDITION if the thread is currently generating, the plan is already active, or the template has no phases. operationId: ActivatePlan responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Plan" 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: agent_id description: Required. The ID of the agent that owns the thread. in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread whose plan to activate. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceActivatePlanBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/stream": get: summary: Stream Thread Events description: |- Subscribe to thread events via SSE Opens a persistent SSE connection that streams all events for the specified thread. **Event Flow:** 1. Historical events are sent first (if the thread has existing events) 2. Live events are streamed as they occur (InputText, OutputText, ToolCall*, etc.) 3. Connection stays open until the client disconnects **SSE Message Format:** Each message contains a JSON-serialized `Event` object in the `data` field: ``` data: {"output_text":{"text":"Hello"}} data: {"generation_complete":{"usage":{"prompt_tokens":10,"completion_tokens":5}}} ``` **Extracting Events:** ```javascript const eventSource = new EventSource('/agents/my-agent/threads/my-thread/stream'); eventSource.onmessage = (e) => { const event = JSON.parse(e.data); if (event.output_text) { console.log('Output:', event.output_text.text); } }; ``` This is the browser-compatible alternative to the gRPC `SubscribeThread` RPC. operationId: StreamThreadEvents responses: "200": description: SSE stream of thread events content: text/event-stream: schema: type: string description: Server-sent events; each `data:` line is a JSON `agentsV1Event`. "404": description: Agent or thread not found parameters: - name: organization_id in: path required: true schema: type: string - name: workspace_id in: path required: true schema: type: string - name: agent_id in: path description: The ID of the agent that owns the thread. required: true schema: type: string - name: thread_id in: path description: The ID of the thread to subscribe to. required: true schema: type: string tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/tool-calls": post: summary: Send Tool Call description: |- Injects a deterministic tool call into a thread. Appends an assistant-voice preamble announcing the call as an externally requested action, then a synthetic ToolCallStart (plus one ToolCallArgument per supplied argument) to the thread event log under the generation lock, executes the tool through the normal dispatcher, and continues with an LLM turn that has the tool result in context. The preamble keeps the model from misattributing the call to itself. operationId: SendToolCall responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1SendToolCallResponse" 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: agent_id description: Required. The ID of the agent that owns the thread. in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to inject the call into. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceSendToolCallBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/tool-results": post: summary: Send Tool Result description: |- Sends a tool execution result for a remote tool. Remote tools pause generation when called, waiting for an external system to execute them and return the result via this RPC. Generation resumes once the result is received. operationId: SendToolResult responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1SendToolResultResponse" 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: agent_id description: Required. The ID of the agent that owns the thread. in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread where the remote tool was called. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceSendToolResultBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/uploads": post: summary: Upload Thread File description: |- Upload a file to a thread Accepts a `multipart/form-data` body with a single `file` part and stores it for the thread under `uploads://`. Returns the artifact URI plus the recorded MIME type, byte size, and filename. The MIME type is taken from the part's `Content-Type` header when the browser supplies one, falls back to a guess based on the filename extension, and finally to `application/octet-stream`. Multipart parts other than `file` are accepted and ignored, leaving room for forward-compatible additions (e.g. a content hash, a TTL override) without breaking older servers. **Client example (browser, with progress):** ```javascript const form = new FormData(); form.append('file', file); const xhr = new XMLHttpRequest(); xhr.upload.onprogress = (e) => { if (e.lengthComputable) { console.log(`uploaded ${e.loaded} / ${e.total}`); } }; xhr.onload = () => { if (xhr.status === 200) { const { uri } = JSON.parse(xhr.responseText); // include `uri` in SendMessage.documents } }; xhr.open('POST', `/api/v1/agents/${agentId}/threads/${threadId}/uploads`); xhr.send(form); ``` operationId: UploadThreadFile responses: "200": description: Upload accepted; artifact written to uploads://<filename>. content: application/json: schema: type: object required: - uri - mime_type - size - filename properties: uri: type: string description: Artifact URI to embed in SendMessage.documents. example: uploads://report.pdf mime_type: type: string description: MIME type recorded on the artifact. example: application/pdf size: type: integer format: int64 description: Size of the stored content in bytes. filename: type: string description: Filename the artifact is stored under within the uploads:// store. "400": description: Multipart body missing the `file` part, missing a filename, or otherwise malformed. "404": description: Agent or thread not found. "413": description: Payload too large (server body-size limit exceeded). "500": description: Internal store error. parameters: - name: organization_id in: path required: true schema: type: string - name: workspace_id in: path required: true schema: type: string - name: agent_id in: path description: The ID of the agent that owns the thread. required: true schema: type: string - name: thread_id in: path description: The ID of the thread the upload is staged into. required: true schema: type: string requestBody: required: true content: multipart/form-data: schema: type: object required: - file properties: file: type: string format: binary description: The file payload. The part's filename and Content-Type are recorded on the artifact. tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}:compact": post: summary: Compact Thread description: |- Starts context compaction for a thread. Compaction summarizes conversation history to reduce context size while preserving essential information. This RPC emits a CompactStart event and returns the compact_id for tracking. The actual compaction is performed asynchronously. Once complete, a CompactComplete event with the summary content should be added to the thread using the returned compact_id. While compaction is in progress (CompactStart without CompactComplete), the UI should block user input. operationId: CompactThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1StartCompactionResponse" 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: agent_id description: Required. The ID of the agent that owns the thread. in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to compact. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceStartCompactionBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}:fork": post: summary: Fork Thread description: |- Forks (duplicates) a thread with all its data. Creates a new thread that is a complete copy of the source thread, including events, feedback, memory customizations, scratchpad, plan, and template config customizations. Returns FAILED_PRECONDITION if the source thread is currently generating. operationId: ForkThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Thread" 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: agent_id description: Required. The agent that owns the thread. in: path required: true schema: type: string - name: thread_id description: Required. The source thread to fork. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceForkThreadBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}:stop": post: summary: Stop Thread description: |- Stops an in-progress generation in a thread. If a generation is currently running, it will be cancelled and a GenerationFailed event with STOPPED kind will be emitted. If no generation is in progress, this is a no-op and returns stopped=false. operationId: StopThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1StopResponse" 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: agent_id description: Required. The ID of the agent that owns the thread. in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread with the generation to stop. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceStopBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}:wake": post: summary: Wake Thread description: |- Wakes a thread that is currently sleeping (UI "Wake up" button). Atomically ends the pending sleep with `interrupted_by_user = true`, cancels the scheduled wake task, and triggers a new generation so the LLM observes the early return in its rebuilt history. No-op when no sleep is pending; the call still triggers a normal Reminder-driven resume in that case. operationId: WakeThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1WakeResponse" 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: agent_id description: Required. The ID of the agent that owns the thread. in: path required: true schema: type: string - name: thread_id description: Required. The ID of the sleeping thread to wake. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceWakeBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/versions": get: summary: List Agent Versions description: |- Lists all versions of an agent. Returns version metadata in ascending order. operationId: ListAgentVersions responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1ListAgentVersionsResponse" 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: agent_id description: The agent ID. in: path required: true schema: type: string tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/versions/{version}": get: summary: Get Agent Version description: Fetches a specific version of an agent's full configuration by version number. operationId: GetAgentVersion responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1GetAgentResponse" 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: agent_id description: Required. The agent ID. in: path required: true schema: type: string - name: version description: Required. The numeric version to fetch. in: path required: true schema: type: string format: uint64 tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/versions/{version}:restore": post: summary: Restore Agent Version description: |- Restores a previous version as a new version at the head. The old version's template becomes the new latest version. All existing versions are preserved. operationId: RestoreAgentVersion responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1RestoreAgentVersionResponse" 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: agent_id description: The agent ID. in: path required: true schema: type: string - name: version description: The version number to restore. in: path required: true schema: type: string format: uint64 requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsAgentServiceRestoreAgentVersionBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/versions/{version}:tag": post: summary: Tag Agent Version description: |- Applies a tag to a specific agent version. Tags are immutable — a tag name can only be used once per agent. To reassign a tag, untag it first, then re-tag. operationId: TagAgentVersion responses: "204": description: No content. 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: agent_id description: The agent ID. in: path required: true schema: type: string - name: version description: The version number to tag. in: path required: true schema: type: string format: uint64 requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsAgentServiceTagAgentVersionBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}:duplicate": post: summary: Duplicate Agent description: |- Duplicates an agent with all its configuration. Creates a new agent that is a complete copy of the source agent, including generator, memory blocks, tool sources with adapters, artifact stores, artifact types, event compactor, and variables. operationId: DuplicateAgent responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1DuplicateAgentResponse" 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: agent_id description: Required. The agent to duplicate. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsAgentServiceDuplicateAgentBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}:export": post: summary: Export Agent description: |- Exports an agent configuration in the specified format. Returns the exported data as bytes with a suggested filename. operationId: ExportAgent responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1ExportAgentResponse" 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: agent_id description: Required. The agent to export. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsAgentServiceExportAgentBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents:import": post: summary: Import Agent description: |- Imports an agent configuration from the specified format. Parses and validates the data, saves the agent to the store. Sub-agent dependencies must exist or be included in the import bundle. operationId: ImportAgent responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1ImportAgentResponse" 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 requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsV1ImportAgentRequest" description: Request message for ImportAgent. required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/hermes/threads": get: summary: List Threads (Hermes, automation) description: |- Lists all threads for an agent. Targets the built-in `hermes` agent in the automation scope; the generic form is `ListThreads` on `/agents/{agent_id}`. operationId: AutomationHermesListThreads responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1ListThreadsResponse" 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: automation_id in: path required: true schema: type: string - name: filter description: |- Optional REL expression filtering over thread fields. Empty = no filter. Supported fields: agent_id (string) status (string, snake_case discriminant) variables., metadata. (string) title, description (optional string) created_at, updated_at (RFC-3339 string literal) agent_version (integer) origin.kind (string: "schedule" / "sub_agent") origin.schedule.schedule_id (string) origin.sub_agent.parent_agent_id (string) origin.sub_agent.parent_thread_id (string) origin.sub_agent.task_id (string) hydration (string: "hydrated" / "dehydrated") Examples: variables.region == "us-east" && updated_at >= "2026-05-01T00:00:00Z" title.contains("invoice") agent_version in [3, 4, 5] origin.kind == "schedule" has(origin.sub_agent.parent_agent_id) in: query required: false schema: type: string tags: - Agents post: summary: Create Thread (Hermes, automation) description: |- Creates a new thread. The thread_id is auto-generated. Optionally provide a title and description. Targets the built-in `hermes` agent in the automation scope; the generic form is `CreateThread` on `/agents/{agent_id}`. operationId: AutomationHermesCreateThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Thread" 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: automation_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceCreateThreadBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/hermes/threads/{thread_id}" : get: summary: Get Thread (Hermes, automation) description: |- Gets a thread by ID. Returns thread metadata and event count without loading the full event history. Returns NOT_FOUND if the thread doesn't exist. Targets the built-in `hermes` agent in the automation scope; the generic form is `GetThread` on `/agents/{agent_id}`. operationId: AutomationHermesGetThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Thread" 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to retrieve. in: path required: true schema: type: string tags: - Agents patch: summary: Update Thread (Hermes, automation) description: |- Updates a thread's title and/or description. Targets the built-in `hermes` agent in the automation scope; the generic form is `UpdateThread` on `/agents/{agent_id}`. operationId: AutomationHermesUpdateThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Thread" 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to update. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceUpdateThreadBody" required: true tags: - Agents delete: summary: Delete Thread (Hermes, automation) description: |- Deletes a thread and all its events. Targets the built-in `hermes` agent in the automation scope; the generic form is `DeleteThread` on `/agents/{agent_id}`. operationId: AutomationHermesDeleteThread responses: "204": description: No content. 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to delete. in: path required: true schema: type: string tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/hermes/threads/{thread_id}/context" : get: summary: Get Thread Context (Hermes, automation) description: |- Gets thread context information including all context items with token counts. Returns a unified view of all items contributing to the context window: - Memory blocks (fixed and volatile) - Enabled tools (fixed) - Conversation history (compactable) Each item includes its token count for context budget management. Targets the built-in `hermes` agent in the automation scope; the generic form is `GetThreadContext` on `/agents/{agent_id}`. operationId: AutomationHermesGetThreadContext responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1GetThreadContextResponse" 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: automation_id in: path required: true schema: type: string - name: thread_id description: The thread ID. in: path required: true schema: type: string tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/hermes/threads/{thread_id}/events" : get: summary: Get Thread Events (Hermes, automation) description: |- Retrieves all events from a thread. This RPC returns the complete history of events for a thread, including user inputs, assistant responses, tool calls, and their results. Events are returned in chronological order. Targets the built-in `hermes` agent in the automation scope; the generic form is `GetThreadEvents` on `/agents/{agent_id}`. operationId: AutomationHermesGetThreadEvents responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1GetEventsResponse" 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to retrieve events from. in: path required: true schema: type: string - name: compacted description: |- Optional. If true, return the compacted view of events. The compacted view shows what the LLM sees: events in compacted ranges are excluded and replaced by CompactComplete events containing summaries. If false (default), returns the full event history for UI display. in: query required: false schema: type: boolean - name: include_deleted description: |- Optional. If true, include deleted events in the response. Deleted events will have the `deleted` field set to true on each event. in: query required: false schema: type: boolean tags: - Agents post: summary: Send Message And Wait (Hermes, automation) description: |- Sends a message and streams back response events synchronously. This RPC adds user input to the specified thread and returns a stream of events representing the assistant's response. Events include output text, tool calls, and completion metadata. Targets the built-in `hermes` agent in the automation scope; the generic form is `SendMessageAndWait` on `/agents/{agent_id}`. operationId: AutomationHermesSendMessageAndWait responses: "200": description: A successful response.(streaming responses) content: application/json: schema: type: object properties: result: $ref: "#/components/schemas/agentsV1Event" error: $ref: "#/components/schemas/rpcStatus" title: Stream result of v1Event 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to send the message to. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceSendMessageSyncBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/hermes/threads/{thread_id}/feedback" : post: summary: Set Thread Feedback (Hermes, automation) description: |- Sets feedback (like/dislike) for a generation response. Feedback is mutually exclusive - setting LIKE removes any DISLIKE and vice versa. Setting the same feedback that already exists is a no-op. Use FEEDBACK_TYPE_UNSPECIFIED to clear existing feedback. Feedback is stored with the thread and is purely for analytics/UI purposes. It is not visible to the LLM. Targets the built-in `hermes` agent in the automation scope; the generic form is `SetThreadFeedback` on `/agents/{agent_id}`. operationId: AutomationHermesSetThreadFeedback responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1SetFeedbackResponse" 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread containing the generation. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceSetFeedbackBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/hermes/threads/{thread_id}/input" : post: summary: Send Message (Hermes, automation) description: |- Sends a message to a thread (fire and forget). The message is added to the thread and generation begins asynchronously. Response events arrive via SubscribeThread stream or SSE, not this RPC. Targets the built-in `hermes` agent in the automation scope; the generic form is `SendMessage` on `/agents/{agent_id}`. operationId: AutomationHermesSendMessage responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1SendMessageResponse" 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to send the message to. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceSendMessageBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/hermes/threads/{thread_id}/stream" : get: summary: Stream Thread Events (Hermes, automation) description: |- Subscribe to thread events via SSE Opens a persistent SSE connection that streams all events for the specified thread. **Event Flow:** 1. Historical events are sent first (if the thread has existing events) 2. Live events are streamed as they occur (InputText, OutputText, ToolCall*, etc.) 3. Connection stays open until the client disconnects **SSE Message Format:** Each message contains a JSON-serialized `Event` object in the `data` field: ``` data: {"output_text":{"text":"Hello"}} data: {"generation_complete":{"usage":{"prompt_tokens":10,"completion_tokens":5}}} ``` **Extracting Events:** ```javascript const eventSource = new EventSource('/agents/my-agent/threads/my-thread/stream'); eventSource.onmessage = (e) => { const event = JSON.parse(e.data); if (event.output_text) { console.log('Output:', event.output_text.text); } }; ``` This is the browser-compatible alternative to the gRPC `SubscribeThread` RPC. Targets the built-in `hermes` agent in the automation scope; the generic form is `StreamThreadEvents` on `/agents/{agent_id}`. operationId: AutomationHermesStreamThreadEvents responses: "200": description: SSE stream of thread events content: text/event-stream: schema: type: string description: Server-sent events; each `data:` line is a JSON `agentsV1Event`. "404": description: Agent or thread not found parameters: - name: organization_id in: path required: true schema: type: string - name: workspace_id in: path required: true schema: type: string - name: automation_id in: path required: true schema: type: string - name: thread_id in: path description: The ID of the thread to subscribe to. required: true schema: type: string tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/hermes/threads/{thread_id}/sub-agents" : get: summary: List Sub Agents (Hermes, automation) description: |- Lists sub-agents configured for a thread. Targets the built-in `hermes` agent in the automation scope; the generic form is `ListSubAgents` on `/agents/{agent_id}`. operationId: AutomationHermesListSubAgents responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1ListSubAgentsResponse" 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. The thread whose sub-agents to list. in: path required: true schema: type: string tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/hermes/threads/{thread_id}/tool-calls" : post: summary: Send Tool Call (Hermes, automation) description: |- Injects a deterministic tool call into a thread. Appends an assistant-voice preamble announcing the call as an externally requested action, then a synthetic ToolCallStart (plus one ToolCallArgument per supplied argument) to the thread event log under the generation lock, executes the tool through the normal dispatcher, and continues with an LLM turn that has the tool result in context. The preamble keeps the model from misattributing the call to itself. Targets the built-in `hermes` agent in the automation scope; the generic form is `SendToolCall` on `/agents/{agent_id}`. operationId: AutomationHermesSendToolCall responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1SendToolCallResponse" 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to inject the call into. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceSendToolCallBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/hermes/threads/{thread_id}/tool-results" : post: summary: Send Tool Result (Hermes, automation) description: |- Sends a tool execution result for a remote tool. Remote tools pause generation when called, waiting for an external system to execute them and return the result via this RPC. Generation resumes once the result is received. Targets the built-in `hermes` agent in the automation scope; the generic form is `SendToolResult` on `/agents/{agent_id}`. operationId: AutomationHermesSendToolResult responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1SendToolResultResponse" 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread where the remote tool was called. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceSendToolResultBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/hermes/threads/{thread_id}/uploads" : post: summary: Upload Thread File (Hermes, automation) description: |- Upload a file to a thread Accepts a `multipart/form-data` body with a single `file` part and stores it for the thread under `uploads://`. Returns the artifact URI plus the recorded MIME type, byte size, and filename. The MIME type is taken from the part's `Content-Type` header when the browser supplies one, falls back to a guess based on the filename extension, and finally to `application/octet-stream`. Multipart parts other than `file` are accepted and ignored, leaving room for forward-compatible additions (e.g. a content hash, a TTL override) without breaking older servers. **Client example (browser, with progress):** ```javascript const form = new FormData(); form.append('file', file); const xhr = new XMLHttpRequest(); xhr.upload.onprogress = (e) => { if (e.lengthComputable) { console.log(`uploaded ${e.loaded} / ${e.total}`); } }; xhr.onload = () => { if (xhr.status === 200) { const { uri } = JSON.parse(xhr.responseText); // include `uri` in SendMessage.documents } }; xhr.open('POST', `/api/v1/agents/${agentId}/threads/${threadId}/uploads`); xhr.send(form); ``` Targets the built-in `hermes` agent in the automation scope; the generic form is `UploadThreadFile` on `/agents/{agent_id}`. operationId: AutomationHermesUploadThreadFile responses: "200": description: Upload accepted; artifact written to uploads://<filename>. content: application/json: schema: type: object required: - uri - mime_type - size - filename properties: uri: type: string description: Artifact URI to embed in SendMessage.documents. example: uploads://report.pdf mime_type: type: string description: MIME type recorded on the artifact. example: application/pdf size: type: integer format: int64 description: Size of the stored content in bytes. filename: type: string description: Filename the artifact is stored under within the uploads:// store. "400": description: Multipart body missing the `file` part, missing a filename, or otherwise malformed. "404": description: Agent or thread not found. "413": description: Payload too large (server body-size limit exceeded). "500": description: Internal store error. parameters: - name: organization_id in: path required: true schema: type: string - name: workspace_id in: path required: true schema: type: string - name: automation_id in: path required: true schema: type: string - name: thread_id in: path description: The ID of the thread the upload is staged into. required: true schema: type: string requestBody: required: true content: multipart/form-data: schema: type: object required: - file properties: file: type: string format: binary description: The file payload. The part's filename and Content-Type are recorded on the artifact. tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/hermes/threads/{thread_id}:compact" : post: summary: Compact Thread (Hermes, automation) description: |- Starts context compaction for a thread. Compaction summarizes conversation history to reduce context size while preserving essential information. This RPC emits a CompactStart event and returns the compact_id for tracking. The actual compaction is performed asynchronously. Once complete, a CompactComplete event with the summary content should be added to the thread using the returned compact_id. While compaction is in progress (CompactStart without CompactComplete), the UI should block user input. Targets the built-in `hermes` agent in the automation scope; the generic form is `CompactThread` on `/agents/{agent_id}`. operationId: AutomationHermesCompactThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1StartCompactionResponse" 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to compact. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceStartCompactionBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/hermes/threads/{thread_id}:fork" : post: summary: Fork Thread (Hermes, automation) description: |- Forks (duplicates) a thread with all its data. Creates a new thread that is a complete copy of the source thread, including events, feedback, memory customizations, scratchpad, plan, and template config customizations. Returns FAILED_PRECONDITION if the source thread is currently generating. Targets the built-in `hermes` agent in the automation scope; the generic form is `ForkThread` on `/agents/{agent_id}`. operationId: AutomationHermesForkThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Thread" 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. The source thread to fork. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceForkThreadBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/hermes/threads/{thread_id}:stop" : post: summary: Stop Thread (Hermes, automation) description: |- Stops an in-progress generation in a thread. If a generation is currently running, it will be cancelled and a GenerationFailed event with STOPPED kind will be emitted. If no generation is in progress, this is a no-op and returns stopped=false. Targets the built-in `hermes` agent in the automation scope; the generic form is `StopThread` on `/agents/{agent_id}`. operationId: AutomationHermesStopThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1StopResponse" 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread with the generation to stop. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceStopBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/hermes/threads/{thread_id}:wake" : post: summary: Wake Thread (Hermes, automation) description: |- Wakes a thread that is currently sleeping (UI "Wake up" button). Atomically ends the pending sleep with `interrupted_by_user = true`, cancels the scheduled wake task, and triggers a new generation so the LLM observes the early return in its rebuilt history. No-op when no sleep is pending; the call still triggers a normal Reminder-driven resume in that case. Targets the built-in `hermes` agent in the automation scope; the generic form is `WakeThread` on `/agents/{agent_id}`. operationId: AutomationHermesWakeThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1WakeResponse" 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the sleeping thread to wake. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceWakeBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/prime/threads": get: summary: List Threads (Prime, automation) description: |- Lists all threads for an agent. Targets the built-in `prime` agent in the automation scope; the generic form is `ListThreads` on `/agents/{agent_id}`. operationId: AutomationPrimeListThreads responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1ListThreadsResponse" 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: automation_id in: path required: true schema: type: string - name: filter description: |- Optional REL expression filtering over thread fields. Empty = no filter. Supported fields: agent_id (string) status (string, snake_case discriminant) variables., metadata. (string) title, description (optional string) created_at, updated_at (RFC-3339 string literal) agent_version (integer) origin.kind (string: "schedule" / "sub_agent") origin.schedule.schedule_id (string) origin.sub_agent.parent_agent_id (string) origin.sub_agent.parent_thread_id (string) origin.sub_agent.task_id (string) hydration (string: "hydrated" / "dehydrated") Examples: variables.region == "us-east" && updated_at >= "2026-05-01T00:00:00Z" title.contains("invoice") agent_version in [3, 4, 5] origin.kind == "schedule" has(origin.sub_agent.parent_agent_id) in: query required: false schema: type: string tags: - Agents post: summary: Create Thread (Prime, automation) description: |- Creates a new thread. The thread_id is auto-generated. Optionally provide a title and description. Targets the built-in `prime` agent in the automation scope; the generic form is `CreateThread` on `/agents/{agent_id}`. operationId: AutomationPrimeCreateThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Thread" 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: automation_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceCreateThreadBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/prime/threads/{thread_id}/events" : get: summary: Get Thread Events (Prime, automation) description: |- Retrieves all events from a thread. This RPC returns the complete history of events for a thread, including user inputs, assistant responses, tool calls, and their results. Events are returned in chronological order. Targets the built-in `prime` agent in the automation scope; the generic form is `GetThreadEvents` on `/agents/{agent_id}`. operationId: AutomationPrimeGetThreadEvents responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1GetEventsResponse" 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to retrieve events from. in: path required: true schema: type: string - name: compacted description: |- Optional. If true, return the compacted view of events. The compacted view shows what the LLM sees: events in compacted ranges are excluded and replaced by CompactComplete events containing summaries. If false (default), returns the full event history for UI display. in: query required: false schema: type: boolean - name: include_deleted description: |- Optional. If true, include deleted events in the response. Deleted events will have the `deleted` field set to true on each event. in: query required: false schema: type: boolean tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/prime/threads/{thread_id}/input" : post: summary: Send Message (Prime, automation) description: |- Sends a message to a thread (fire and forget). The message is added to the thread and generation begins asynchronously. Response events arrive via SubscribeThread stream or SSE, not this RPC. Targets the built-in `prime` agent in the automation scope; the generic form is `SendMessage` on `/agents/{agent_id}`. operationId: AutomationPrimeSendMessage responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1SendMessageResponse" 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to send the message to. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceSendMessageBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/prime/threads/{thread_id}/stream" : get: summary: Stream Thread Events (Prime, automation) description: |- Subscribe to thread events via SSE Opens a persistent SSE connection that streams all events for the specified thread. **Event Flow:** 1. Historical events are sent first (if the thread has existing events) 2. Live events are streamed as they occur (InputText, OutputText, ToolCall*, etc.) 3. Connection stays open until the client disconnects **SSE Message Format:** Each message contains a JSON-serialized `Event` object in the `data` field: ``` data: {"output_text":{"text":"Hello"}} data: {"generation_complete":{"usage":{"prompt_tokens":10,"completion_tokens":5}}} ``` **Extracting Events:** ```javascript const eventSource = new EventSource('/agents/my-agent/threads/my-thread/stream'); eventSource.onmessage = (e) => { const event = JSON.parse(e.data); if (event.output_text) { console.log('Output:', event.output_text.text); } }; ``` This is the browser-compatible alternative to the gRPC `SubscribeThread` RPC. Targets the built-in `prime` agent in the automation scope; the generic form is `StreamThreadEvents` on `/agents/{agent_id}`. operationId: AutomationPrimeStreamThreadEvents responses: "200": description: SSE stream of thread events content: text/event-stream: schema: type: string description: Server-sent events; each `data:` line is a JSON `agentsV1Event`. "404": description: Agent or thread not found parameters: - name: organization_id in: path required: true schema: type: string - name: workspace_id in: path required: true schema: type: string - name: automation_id in: path required: true schema: type: string - name: thread_id in: path description: The ID of the thread to subscribe to. required: true schema: type: string tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/prime/threads/{thread_id}/tool-calls" : post: summary: Send Tool Call (Prime, automation) description: |- Injects a deterministic tool call into a thread. Appends an assistant-voice preamble announcing the call as an externally requested action, then a synthetic ToolCallStart (plus one ToolCallArgument per supplied argument) to the thread event log under the generation lock, executes the tool through the normal dispatcher, and continues with an LLM turn that has the tool result in context. The preamble keeps the model from misattributing the call to itself. Targets the built-in `prime` agent in the automation scope; the generic form is `SendToolCall` on `/agents/{agent_id}`. operationId: AutomationPrimeSendToolCall responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1SendToolCallResponse" 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to inject the call into. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceSendToolCallBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/prime/threads/{thread_id}/tool-results" : post: summary: Send Tool Result (Prime, automation) description: |- Sends a tool execution result for a remote tool. Remote tools pause generation when called, waiting for an external system to execute them and return the result via this RPC. Generation resumes once the result is received. Targets the built-in `prime` agent in the automation scope; the generic form is `SendToolResult` on `/agents/{agent_id}`. operationId: AutomationPrimeSendToolResult responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1SendToolResultResponse" 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread where the remote tool was called. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceSendToolResultBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/prime/threads/{thread_id}/uploads" : post: summary: Upload Thread File (Prime, automation) description: |- Upload a file to a thread Accepts a `multipart/form-data` body with a single `file` part and stores it for the thread under `uploads://`. Returns the artifact URI plus the recorded MIME type, byte size, and filename. The MIME type is taken from the part's `Content-Type` header when the browser supplies one, falls back to a guess based on the filename extension, and finally to `application/octet-stream`. Multipart parts other than `file` are accepted and ignored, leaving room for forward-compatible additions (e.g. a content hash, a TTL override) without breaking older servers. **Client example (browser, with progress):** ```javascript const form = new FormData(); form.append('file', file); const xhr = new XMLHttpRequest(); xhr.upload.onprogress = (e) => { if (e.lengthComputable) { console.log(`uploaded ${e.loaded} / ${e.total}`); } }; xhr.onload = () => { if (xhr.status === 200) { const { uri } = JSON.parse(xhr.responseText); // include `uri` in SendMessage.documents } }; xhr.open('POST', `/api/v1/agents/${agentId}/threads/${threadId}/uploads`); xhr.send(form); ``` Targets the built-in `prime` agent in the automation scope; the generic form is `UploadThreadFile` on `/agents/{agent_id}`. operationId: AutomationPrimeUploadThreadFile responses: "200": description: Upload accepted; artifact written to uploads://<filename>. content: application/json: schema: type: object required: - uri - mime_type - size - filename properties: uri: type: string description: Artifact URI to embed in SendMessage.documents. example: uploads://report.pdf mime_type: type: string description: MIME type recorded on the artifact. example: application/pdf size: type: integer format: int64 description: Size of the stored content in bytes. filename: type: string description: Filename the artifact is stored under within the uploads:// store. "400": description: Multipart body missing the `file` part, missing a filename, or otherwise malformed. "404": description: Agent or thread not found. "413": description: Payload too large (server body-size limit exceeded). "500": description: Internal store error. parameters: - name: organization_id in: path required: true schema: type: string - name: workspace_id in: path required: true schema: type: string - name: automation_id in: path required: true schema: type: string - name: thread_id in: path description: The ID of the thread the upload is staged into. required: true schema: type: string requestBody: required: true content: multipart/form-data: schema: type: object required: - file properties: file: type: string format: binary description: The file payload. The part's filename and Content-Type are recorded on the artifact. tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/prime/threads/{thread_id}:stop" : post: summary: Stop Thread (Prime, automation) description: |- Stops an in-progress generation in a thread. If a generation is currently running, it will be cancelled and a GenerationFailed event with STOPPED kind will be emitted. If no generation is in progress, this is a no-op and returns stopped=false. Targets the built-in `prime` agent in the automation scope; the generic form is `StopThread` on `/agents/{agent_id}`. operationId: AutomationPrimeStopThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1StopResponse" 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread with the generation to stop. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceStopBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/prime/threads/{thread_id}:wake" : post: summary: Wake Thread (Prime, automation) description: |- Wakes a thread that is currently sleeping (UI "Wake up" button). Atomically ends the pending sleep with `interrupted_by_user = true`, cancels the scheduled wake task, and triggers a new generation so the LLM observes the early return in its rebuilt history. No-op when no sleep is pending; the call still triggers a normal Reminder-driven resume in that case. Targets the built-in `prime` agent in the automation scope; the generic form is `WakeThread` on `/agents/{agent_id}`. operationId: AutomationPrimeWakeThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1WakeResponse" 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the sleeping thread to wake. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceWakeBody" required: true tags: - Agents "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads": get: summary: List Threads (Quill2, automation) description: |- Lists all threads for an agent. Targets the built-in `quill2` agent in the automation scope; the generic form is `ListThreads` on `/agents/{agent_id}`. operationId: AutomationQuill2ListThreads responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1ListThreadsResponse" 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: automation_id in: path required: true schema: type: string - name: filter description: |- Optional REL expression filtering over thread fields. Empty = no filter. Supported fields: agent_id (string) status (string, snake_case discriminant) variables., metadata. (string) title, description (optional string) created_at, updated_at (RFC-3339 string literal) agent_version (integer) origin.kind (string: "schedule" / "sub_agent") origin.schedule.schedule_id (string) origin.sub_agent.parent_agent_id (string) origin.sub_agent.parent_thread_id (string) origin.sub_agent.task_id (string) hydration (string: "hydrated" / "dehydrated") Examples: variables.region == "us-east" && updated_at >= "2026-05-01T00:00:00Z" title.contains("invoice") agent_version in [3, 4, 5] origin.kind == "schedule" has(origin.sub_agent.parent_agent_id) in: query required: false schema: type: string tags: - Agents post: summary: Create Thread (Quill2, automation) description: |- Creates a new thread. The thread_id is auto-generated. Optionally provide a title and description. Targets the built-in `quill2` agent in the automation scope; the generic form is `CreateThread` on `/agents/{agent_id}`. operationId: AutomationQuill2CreateThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Thread" 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: automation_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceCreateThreadBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}" : get: summary: Get Thread (Quill2, automation) description: |- Gets a thread by ID. Returns thread metadata and event count without loading the full event history. Returns NOT_FOUND if the thread doesn't exist. Targets the built-in `quill2` agent in the automation scope; the generic form is `GetThread` on `/agents/{agent_id}`. operationId: AutomationQuill2GetThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Thread" 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to retrieve. in: path required: true schema: type: string tags: - Agents patch: summary: Update Thread (Quill2, automation) description: |- Updates a thread's title and/or description. Targets the built-in `quill2` agent in the automation scope; the generic form is `UpdateThread` on `/agents/{agent_id}`. operationId: AutomationQuill2UpdateThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Thread" 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to update. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceUpdateThreadBody" required: true tags: - Agents delete: summary: Delete Thread (Quill2, automation) description: |- Deletes a thread and all its events. Targets the built-in `quill2` agent in the automation scope; the generic form is `DeleteThread` on `/agents/{agent_id}`. operationId: AutomationQuill2DeleteThread responses: "204": description: No content. 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to delete. in: path required: true schema: type: string tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}/artifacts" : get: summary: List Artifacts (Quill2, automation) description: |- Lists artifacts with optional filters. Supports S3-style delimiter for folder navigation. Thread ID is required for variable-scoped artifact access. Targets the built-in `quill2` agent in the automation scope; the generic form is `ListArtifacts` on `/agents/{agent_id}`. operationId: AutomationQuill2ListArtifacts responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1ListArtifactsResponse" 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. Thread ID for variable-scoped artifact access. in: path required: true schema: type: string - name: prefix description: |- Optional. Filter by URI prefix (e.g., "workspace://src/"). If not specified, lists from all stores. in: query required: false schema: type: string - name: delimiter description: Optional. Delimiter for S3-style folder grouping (typically "/"). in: query required: false schema: type: string - name: mime_type description: Optional. Filter by MIME type prefix (e.g., "text/", "image/"). in: query required: false schema: type: string - name: limit description: Optional. Maximum number of results. in: query required: false schema: type: integer format: int64 tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}/artifacts/{artifact_uri}" : get: summary: Get Artifact (Quill2, automation) description: |- Gets artifact metadata by URI. Targets the built-in `quill2` agent in the automation scope; the generic form is `GetArtifact` on `/agents/{agent_id}`. operationId: AutomationQuill2GetArtifact responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Artifact" 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. Thread ID for variable-scoped artifact access. in: path required: true schema: type: string - name: artifact_uri description: Required. The artifact URI (e.g., "workspace://src/main.rs"). Percent-encode the URI in the path, for example `workspace%3A%2F%2Fsrc%2Fmain.rs`. in: path required: true schema: type: string tags: - Agents put: summary: Update Artifact (Quill2, automation) description: |- Creates or updates an artifact. Targets the built-in `quill2` agent in the automation scope; the generic form is `UpdateArtifact` on `/agents/{agent_id}`. operationId: AutomationQuill2UpdateArtifact responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Artifact" 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. Thread ID for variable-scoped artifact access. in: path required: true schema: type: string - name: artifact_uri description: Required. The artifact URI (e.g., "workspace://src/main.rs"). Percent-encode the URI in the path, for example `workspace%3A%2F%2Fsrc%2Fmain.rs`. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceUpdateArtifactBody" required: true tags: - Agents delete: summary: Delete Artifact (Quill2, automation) description: |- Deletes an artifact by URI. Targets the built-in `quill2` agent in the automation scope; the generic form is `DeleteArtifact` on `/agents/{agent_id}`. operationId: AutomationQuill2DeleteArtifact responses: "204": description: No content. 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. Thread ID for variable-scoped artifact access. in: path required: true schema: type: string - name: artifact_uri description: Required. The artifact URI (e.g., "workspace://src/main.rs"). Percent-encode the URI in the path, for example `workspace%3A%2F%2Fsrc%2Fmain.rs`. in: path required: true schema: type: string tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}/artifacts/{artifact_uri}:content" : get: summary: Get Artifact Content (Quill2, automation) description: |- Gets artifact content by URI. Targets the built-in `quill2` agent in the automation scope; the generic form is `GetArtifactContent` on `/agents/{agent_id}`. operationId: AutomationQuill2GetArtifactContent responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1ArtifactContentResponse" 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. Thread ID for variable-scoped artifact access. in: path required: true schema: type: string - name: artifact_uri description: Required. The artifact URI (e.g., "workspace://src/main.rs"). Percent-encode the URI in the path, for example `workspace%3A%2F%2Fsrc%2Fmain.rs`. in: path required: true schema: type: string tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}/artifacts/{artifact_uri}:diff" : get: summary: Get Artifact Diff (Quill2, automation) description: |- Gets the diff for a single staged artifact. Returns the unified diff for a specific artifact if it has staged changes. Returns empty diff for binary files or if no changes exist. Targets the built-in `quill2` agent in the automation scope; the generic form is `GetArtifactDiff` on `/agents/{agent_id}`. operationId: AutomationQuill2GetArtifactDiff responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1GetArtifactDiffResponse" 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. Thread ID for variable-scoped artifact access. in: path required: true schema: type: string - name: artifact_uri description: Required. The artifact URI (e.g., "workspace://src/main.rs"). Percent-encode the URI in the path, for example `workspace%3A%2F%2Fsrc%2Fmain.rs`. in: path required: true schema: type: string tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}/artifacts:commit" : post: summary: Commit Artifacts (Quill2, automation) description: |- Commits staged artifact changes to the underlying store. Persists all staged changes (additions, modifications, deletions) to the underlying store. For stores without staging, this is a no-op. Targets the built-in `quill2` agent in the automation scope; the generic form is `CommitArtifacts` on `/agents/{agent_id}`. operationId: AutomationQuill2CommitArtifacts responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1CommitArtifactsResponse" 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. Thread ID for variable-scoped artifact access. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceCommitArtifactsBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}/artifacts:diff" : post: summary: Diff Artifacts (Quill2, automation) description: |- Gets staged artifact changes with optional diff content. Returns information about artifacts that have been modified but not yet committed. For stores with staging enabled, this shows pending changes. For stores without staging, returns an empty response. Targets the built-in `quill2` agent in the automation scope; the generic form is `DiffArtifacts` on `/agents/{agent_id}`. operationId: AutomationQuill2DiffArtifacts responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1DiffArtifactsResponse" 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. Thread ID for variable-scoped artifact access. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceDiffArtifactsBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}/artifacts:discard" : post: summary: Discard Artifacts (Quill2, automation) description: |- Discards all staged artifact changes without committing. Clears all pending changes (additions, modifications, deletions) from the staging area. For stores without staging, this is a no-op. Targets the built-in `quill2` agent in the automation scope; the generic form is `DiscardArtifacts` on `/agents/{agent_id}`. operationId: AutomationQuill2DiscardArtifacts responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1DiscardArtifactsResponse" 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. Thread ID for variable-scoped artifact access. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceDiscardArtifactsBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}/artifacts:grep" : post: summary: Grep Artifacts (Quill2, automation) description: |- Searches artifact contents using regex pattern matching. Targets the built-in `quill2` agent in the automation scope; the generic form is `GrepArtifacts` on `/agents/{agent_id}`. operationId: AutomationQuill2GrepArtifacts responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1GrepArtifactsResponse" 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. Thread ID for variable-scoped artifact access. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceGrepArtifactsBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}/artifacts:staging" : get: summary: Get Artifacts Staging Summary (Quill2, automation) description: |- Gets a summary of staged artifact changes. Returns a lightweight summary of pending changes including counts and change metadata without diff content. Use DiffArtifacts for full diffs. Targets the built-in `quill2` agent in the automation scope; the generic form is `GetArtifactsStagingSummary` on `/agents/{agent_id}`. operationId: AutomationQuill2GetArtifactsStagingSummary responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1GetArtifactsStagingSummaryResponse" 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. Thread ID for variable-scoped artifact access. in: path required: true schema: type: string - name: prefix description: |- Optional. Store prefix to limit summary scope (e.g., "workspace://"). If not specified, returns summary for all stores. in: query required: false schema: type: string tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}/context" : get: summary: Get Thread Context (Quill2, automation) description: |- Gets thread context information including all context items with token counts. Returns a unified view of all items contributing to the context window: - Memory blocks (fixed and volatile) - Enabled tools (fixed) - Conversation history (compactable) Each item includes its token count for context budget management. Targets the built-in `quill2` agent in the automation scope; the generic form is `GetThreadContext` on `/agents/{agent_id}`. operationId: AutomationQuill2GetThreadContext responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1GetThreadContextResponse" 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: automation_id in: path required: true schema: type: string - name: thread_id description: The thread ID. in: path required: true schema: type: string tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}/events" : get: summary: Get Thread Events (Quill2, automation) description: |- Retrieves all events from a thread. This RPC returns the complete history of events for a thread, including user inputs, assistant responses, tool calls, and their results. Events are returned in chronological order. Targets the built-in `quill2` agent in the automation scope; the generic form is `GetThreadEvents` on `/agents/{agent_id}`. operationId: AutomationQuill2GetThreadEvents responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1GetEventsResponse" 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to retrieve events from. in: path required: true schema: type: string - name: compacted description: |- Optional. If true, return the compacted view of events. The compacted view shows what the LLM sees: events in compacted ranges are excluded and replaced by CompactComplete events containing summaries. If false (default), returns the full event history for UI display. in: query required: false schema: type: boolean - name: include_deleted description: |- Optional. If true, include deleted events in the response. Deleted events will have the `deleted` field set to true on each event. in: query required: false schema: type: boolean tags: - Agents post: summary: Send Message And Wait (Quill2, automation) description: |- Sends a message and streams back response events synchronously. This RPC adds user input to the specified thread and returns a stream of events representing the assistant's response. Events include output text, tool calls, and completion metadata. Targets the built-in `quill2` agent in the automation scope; the generic form is `SendMessageAndWait` on `/agents/{agent_id}`. operationId: AutomationQuill2SendMessageAndWait responses: "200": description: A successful response.(streaming responses) content: application/json: schema: type: object properties: result: $ref: "#/components/schemas/agentsV1Event" error: $ref: "#/components/schemas/rpcStatus" title: Stream result of v1Event 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to send the message to. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceSendMessageSyncBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}/feedback" : post: summary: Set Thread Feedback (Quill2, automation) description: |- Sets feedback (like/dislike) for a generation response. Feedback is mutually exclusive - setting LIKE removes any DISLIKE and vice versa. Setting the same feedback that already exists is a no-op. Use FEEDBACK_TYPE_UNSPECIFIED to clear existing feedback. Feedback is stored with the thread and is purely for analytics/UI purposes. It is not visible to the LLM. Targets the built-in `quill2` agent in the automation scope; the generic form is `SetThreadFeedback` on `/agents/{agent_id}`. operationId: AutomationQuill2SetThreadFeedback responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1SetFeedbackResponse" 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread containing the generation. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceSetFeedbackBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}/input" : post: summary: Send Message (Quill2, automation) description: |- Sends a message to a thread (fire and forget). The message is added to the thread and generation begins asynchronously. Response events arrive via SubscribeThread stream or SSE, not this RPC. Targets the built-in `quill2` agent in the automation scope; the generic form is `SendMessage` on `/agents/{agent_id}`. operationId: AutomationQuill2SendMessage responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1SendMessageResponse" 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to send the message to. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceSendMessageBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}/plan/active" : get: summary: Get Active Plan (Quill2, automation) description: |- Gets the active plan snapshot for a thread (with per-step statuses). Distinct from `GET /plan`, which returns the template. Returns NOT_FOUND if no active plan exists. Targets the built-in `quill2` agent in the automation scope; the generic form is `GetActivePlan` on `/agents/{agent_id}`. operationId: AutomationQuill2GetActivePlan responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Plan" 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to get the plan for. in: path required: true schema: type: string tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}/plan/active/phases/{phase_index}/steps/{step_index}:mark" : post: summary: Mark Plan Step (Quill2, automation) description: |- Marks a step on the active plan as completed or failed. Returns NOT_FOUND if no active plan exists or the phase/step index is invalid. Returns FAILED_PRECONDITION if the thread is currently generating, the step is not in the active phase, or the step is already resolved. Targets the built-in `quill2` agent in the automation scope; the generic form is `MarkPlanStep` on `/agents/{agent_id}`. operationId: AutomationQuill2MarkPlanStep responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Plan" 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread whose plan to modify. in: path required: true schema: type: string - name: phase_index description: Required. 1-indexed phase position. in: path required: true schema: type: integer format: int64 - name: step_index description: Required. 1-indexed step position. in: path required: true schema: type: integer format: int64 requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceMarkStepBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}/plan/active:deactivate" : post: summary: Deactivate Plan (Quill2, automation) description: |- Deactivates the active plan. The snapshot is kept (flagged inactive) for status carry-over on the next activation. No generation guard — always allowed. Returns NOT_FOUND if no active plan exists. Returns FAILED_PRECONDITION if the plan is not active. Targets the built-in `quill2` agent in the automation scope; the generic form is `DeactivatePlan` on `/agents/{agent_id}`. operationId: AutomationQuill2DeactivatePlan responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Plan" 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread whose plan to deactivate. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceDeactivatePlanBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}/plan/active:reset" : post: summary: Reset Plan (Quill2, automation) description: |- Resets all step statuses on the active plan back to pending. Clears all step statuses and failure reasons. If the plan is active, it is deactivated first before resetting. Returns NOT_FOUND if no active plan exists. Returns FAILED_PRECONDITION if the thread is currently generating. Targets the built-in `quill2` agent in the automation scope; the generic form is `ResetPlan` on `/agents/{agent_id}`. operationId: AutomationQuill2ResetPlan responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Plan" 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread whose plan to reset. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceResetPlanBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}/plan:activate" : post: summary: Activate Plan (Quill2, automation) description: |- Activates the plan for a thread. Snapshots the current template plan and carries over statuses from any previous snapshot by id. Returns NOT_FOUND if no plan template exists. Returns FAILED_PRECONDITION if the thread is currently generating, the plan is already active, or the template has no phases. Targets the built-in `quill2` agent in the automation scope; the generic form is `ActivatePlan` on `/agents/{agent_id}`. operationId: AutomationQuill2ActivatePlan responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Plan" 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread whose plan to activate. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceActivatePlanBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}/stream" : get: summary: Stream Thread Events (Quill2, automation) description: |- Subscribe to thread events via SSE Opens a persistent SSE connection that streams all events for the specified thread. **Event Flow:** 1. Historical events are sent first (if the thread has existing events) 2. Live events are streamed as they occur (InputText, OutputText, ToolCall*, etc.) 3. Connection stays open until the client disconnects **SSE Message Format:** Each message contains a JSON-serialized `Event` object in the `data` field: ``` data: {"output_text":{"text":"Hello"}} data: {"generation_complete":{"usage":{"prompt_tokens":10,"completion_tokens":5}}} ``` **Extracting Events:** ```javascript const eventSource = new EventSource('/agents/my-agent/threads/my-thread/stream'); eventSource.onmessage = (e) => { const event = JSON.parse(e.data); if (event.output_text) { console.log('Output:', event.output_text.text); } }; ``` This is the browser-compatible alternative to the gRPC `SubscribeThread` RPC. Targets the built-in `quill2` agent in the automation scope; the generic form is `StreamThreadEvents` on `/agents/{agent_id}`. operationId: AutomationQuill2StreamThreadEvents responses: "200": description: SSE stream of thread events content: text/event-stream: schema: type: string description: Server-sent events; each `data:` line is a JSON `agentsV1Event`. "404": description: Agent or thread not found parameters: - name: organization_id in: path required: true schema: type: string - name: workspace_id in: path required: true schema: type: string - name: automation_id in: path required: true schema: type: string - name: thread_id in: path description: The ID of the thread to subscribe to. required: true schema: type: string tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}/sub-agents" : get: summary: List Sub Agents (Quill2, automation) description: |- Lists sub-agents configured for a thread. Targets the built-in `quill2` agent in the automation scope; the generic form is `ListSubAgents` on `/agents/{agent_id}`. operationId: AutomationQuill2ListSubAgents responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1ListSubAgentsResponse" 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. The thread whose sub-agents to list. in: path required: true schema: type: string tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}/tool-calls" : post: summary: Send Tool Call (Quill2, automation) description: |- Injects a deterministic tool call into a thread. Appends an assistant-voice preamble announcing the call as an externally requested action, then a synthetic ToolCallStart (plus one ToolCallArgument per supplied argument) to the thread event log under the generation lock, executes the tool through the normal dispatcher, and continues with an LLM turn that has the tool result in context. The preamble keeps the model from misattributing the call to itself. Targets the built-in `quill2` agent in the automation scope; the generic form is `SendToolCall` on `/agents/{agent_id}`. operationId: AutomationQuill2SendToolCall responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1SendToolCallResponse" 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to inject the call into. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceSendToolCallBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}/tool-results" : post: summary: Send Tool Result (Quill2, automation) description: |- Sends a tool execution result for a remote tool. Remote tools pause generation when called, waiting for an external system to execute them and return the result via this RPC. Generation resumes once the result is received. Targets the built-in `quill2` agent in the automation scope; the generic form is `SendToolResult` on `/agents/{agent_id}`. operationId: AutomationQuill2SendToolResult responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1SendToolResultResponse" 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread where the remote tool was called. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceSendToolResultBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}/uploads" : post: summary: Upload Thread File (Quill2, automation) description: |- Upload a file to a thread Accepts a `multipart/form-data` body with a single `file` part and stores it for the thread under `uploads://`. Returns the artifact URI plus the recorded MIME type, byte size, and filename. The MIME type is taken from the part's `Content-Type` header when the browser supplies one, falls back to a guess based on the filename extension, and finally to `application/octet-stream`. Multipart parts other than `file` are accepted and ignored, leaving room for forward-compatible additions (e.g. a content hash, a TTL override) without breaking older servers. **Client example (browser, with progress):** ```javascript const form = new FormData(); form.append('file', file); const xhr = new XMLHttpRequest(); xhr.upload.onprogress = (e) => { if (e.lengthComputable) { console.log(`uploaded ${e.loaded} / ${e.total}`); } }; xhr.onload = () => { if (xhr.status === 200) { const { uri } = JSON.parse(xhr.responseText); // include `uri` in SendMessage.documents } }; xhr.open('POST', `/api/v1/agents/${agentId}/threads/${threadId}/uploads`); xhr.send(form); ``` Targets the built-in `quill2` agent in the automation scope; the generic form is `UploadThreadFile` on `/agents/{agent_id}`. operationId: AutomationQuill2UploadThreadFile responses: "200": description: Upload accepted; artifact written to uploads://<filename>. content: application/json: schema: type: object required: - uri - mime_type - size - filename properties: uri: type: string description: Artifact URI to embed in SendMessage.documents. example: uploads://report.pdf mime_type: type: string description: MIME type recorded on the artifact. example: application/pdf size: type: integer format: int64 description: Size of the stored content in bytes. filename: type: string description: Filename the artifact is stored under within the uploads:// store. "400": description: Multipart body missing the `file` part, missing a filename, or otherwise malformed. "404": description: Agent or thread not found. "413": description: Payload too large (server body-size limit exceeded). "500": description: Internal store error. parameters: - name: organization_id in: path required: true schema: type: string - name: workspace_id in: path required: true schema: type: string - name: automation_id in: path required: true schema: type: string - name: thread_id in: path description: The ID of the thread the upload is staged into. required: true schema: type: string requestBody: required: true content: multipart/form-data: schema: type: object required: - file properties: file: type: string format: binary description: The file payload. The part's filename and Content-Type are recorded on the artifact. tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}:compact" : post: summary: Compact Thread (Quill2, automation) description: |- Starts context compaction for a thread. Compaction summarizes conversation history to reduce context size while preserving essential information. This RPC emits a CompactStart event and returns the compact_id for tracking. The actual compaction is performed asynchronously. Once complete, a CompactComplete event with the summary content should be added to the thread using the returned compact_id. While compaction is in progress (CompactStart without CompactComplete), the UI should block user input. Targets the built-in `quill2` agent in the automation scope; the generic form is `CompactThread` on `/agents/{agent_id}`. operationId: AutomationQuill2CompactThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1StartCompactionResponse" 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to compact. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceStartCompactionBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}:fork" : post: summary: Fork Thread (Quill2, automation) description: |- Forks (duplicates) a thread with all its data. Creates a new thread that is a complete copy of the source thread, including events, feedback, memory customizations, scratchpad, plan, and template config customizations. Returns FAILED_PRECONDITION if the source thread is currently generating. Targets the built-in `quill2` agent in the automation scope; the generic form is `ForkThread` on `/agents/{agent_id}`. operationId: AutomationQuill2ForkThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Thread" 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. The source thread to fork. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceForkThreadBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}:stop" : post: summary: Stop Thread (Quill2, automation) description: |- Stops an in-progress generation in a thread. If a generation is currently running, it will be cancelled and a GenerationFailed event with STOPPED kind will be emitted. If no generation is in progress, this is a no-op and returns stopped=false. Targets the built-in `quill2` agent in the automation scope; the generic form is `StopThread` on `/agents/{agent_id}`. operationId: AutomationQuill2StopThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1StopResponse" 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread with the generation to stop. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceStopBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}:wake" : post: summary: Wake Thread (Quill2, automation) description: |- Wakes a thread that is currently sleeping (UI "Wake up" button). Atomically ends the pending sleep with `interrupted_by_user = true`, cancels the scheduled wake task, and triggers a new generation so the LLM observes the early return in its rebuilt history. No-op when no sleep is pending; the call still triggers a normal Reminder-driven resume in that case. Targets the built-in `quill2` agent in the automation scope; the generic form is `WakeThread` on `/agents/{agent_id}`. operationId: AutomationQuill2WakeThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1WakeResponse" 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: automation_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the sleeping thread to wake. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceWakeBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral-lite/threads" : get: summary: List Threads (Astral Lite, run) description: |- Lists all threads for an agent. Targets the built-in `astral-lite` agent in the run scope; the generic form is `ListThreads` on `/agents/{agent_id}`. operationId: RunAstralLiteListThreads responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1ListThreadsResponse" 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: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string - name: filter description: |- Optional REL expression filtering over thread fields. Empty = no filter. Supported fields: agent_id (string) status (string, snake_case discriminant) variables., metadata. (string) title, description (optional string) created_at, updated_at (RFC-3339 string literal) agent_version (integer) origin.kind (string: "schedule" / "sub_agent") origin.schedule.schedule_id (string) origin.sub_agent.parent_agent_id (string) origin.sub_agent.parent_thread_id (string) origin.sub_agent.task_id (string) hydration (string: "hydrated" / "dehydrated") Examples: variables.region == "us-east" && updated_at >= "2026-05-01T00:00:00Z" title.contains("invoice") agent_version in [3, 4, 5] origin.kind == "schedule" has(origin.sub_agent.parent_agent_id) in: query required: false schema: type: string tags: - Agents post: summary: Create Thread (Astral Lite, run) description: |- Creates a new thread. The thread_id is auto-generated. Optionally provide a title and description. Targets the built-in `astral-lite` agent in the run scope; the generic form is `CreateThread` on `/agents/{agent_id}`. operationId: RunAstralLiteCreateThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Thread" 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: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceCreateThreadBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral-lite/threads/{thread_id}" : get: summary: Get Thread (Astral Lite, run) description: |- Gets a thread by ID. Returns thread metadata and event count without loading the full event history. Returns NOT_FOUND if the thread doesn't exist. Targets the built-in `astral-lite` agent in the run scope; the generic form is `GetThread` on `/agents/{agent_id}`. operationId: RunAstralLiteGetThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Thread" 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: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to retrieve. in: path required: true schema: type: string tags: - Agents patch: summary: Update Thread (Astral Lite, run) description: |- Updates a thread's title and/or description. Targets the built-in `astral-lite` agent in the run scope; the generic form is `UpdateThread` on `/agents/{agent_id}`. operationId: RunAstralLiteUpdateThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Thread" 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: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to update. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceUpdateThreadBody" required: true tags: - Agents delete: summary: Delete Thread (Astral Lite, run) description: |- Deletes a thread and all its events. Targets the built-in `astral-lite` agent in the run scope; the generic form is `DeleteThread` on `/agents/{agent_id}`. operationId: RunAstralLiteDeleteThread responses: "204": description: No content. 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: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to delete. in: path required: true schema: type: string tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral-lite/threads/{thread_id}/context" : get: summary: Get Thread Context (Astral Lite, run) description: |- Gets thread context information including all context items with token counts. Returns a unified view of all items contributing to the context window: - Memory blocks (fixed and volatile) - Enabled tools (fixed) - Conversation history (compactable) Each item includes its token count for context budget management. Targets the built-in `astral-lite` agent in the run scope; the generic form is `GetThreadContext` on `/agents/{agent_id}`. operationId: RunAstralLiteGetThreadContext responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1GetThreadContextResponse" 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: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string - name: thread_id description: The thread ID. in: path required: true schema: type: string tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral-lite/threads/{thread_id}/events" : get: summary: Get Thread Events (Astral Lite, run) description: |- Retrieves all events from a thread. This RPC returns the complete history of events for a thread, including user inputs, assistant responses, tool calls, and their results. Events are returned in chronological order. Targets the built-in `astral-lite` agent in the run scope; the generic form is `GetThreadEvents` on `/agents/{agent_id}`. operationId: RunAstralLiteGetThreadEvents responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1GetEventsResponse" 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: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to retrieve events from. in: path required: true schema: type: string - name: compacted description: |- Optional. If true, return the compacted view of events. The compacted view shows what the LLM sees: events in compacted ranges are excluded and replaced by CompactComplete events containing summaries. If false (default), returns the full event history for UI display. in: query required: false schema: type: boolean - name: include_deleted description: |- Optional. If true, include deleted events in the response. Deleted events will have the `deleted` field set to true on each event. in: query required: false schema: type: boolean tags: - Agents post: summary: Send Message And Wait (Astral Lite, run) description: |- Sends a message and streams back response events synchronously. This RPC adds user input to the specified thread and returns a stream of events representing the assistant's response. Events include output text, tool calls, and completion metadata. Targets the built-in `astral-lite` agent in the run scope; the generic form is `SendMessageAndWait` on `/agents/{agent_id}`. operationId: RunAstralLiteSendMessageAndWait responses: "200": description: A successful response.(streaming responses) content: application/json: schema: type: object properties: result: $ref: "#/components/schemas/agentsV1Event" error: $ref: "#/components/schemas/rpcStatus" title: Stream result of v1Event 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: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to send the message to. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceSendMessageSyncBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral-lite/threads/{thread_id}/feedback" : post: summary: Set Thread Feedback (Astral Lite, run) description: |- Sets feedback (like/dislike) for a generation response. Feedback is mutually exclusive - setting LIKE removes any DISLIKE and vice versa. Setting the same feedback that already exists is a no-op. Use FEEDBACK_TYPE_UNSPECIFIED to clear existing feedback. Feedback is stored with the thread and is purely for analytics/UI purposes. It is not visible to the LLM. Targets the built-in `astral-lite` agent in the run scope; the generic form is `SetThreadFeedback` on `/agents/{agent_id}`. operationId: RunAstralLiteSetThreadFeedback responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1SetFeedbackResponse" 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: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread containing the generation. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceSetFeedbackBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral-lite/threads/{thread_id}/input" : post: summary: Send Message (Astral Lite, run) description: |- Sends a message to a thread (fire and forget). The message is added to the thread and generation begins asynchronously. Response events arrive via SubscribeThread stream or SSE, not this RPC. Targets the built-in `astral-lite` agent in the run scope; the generic form is `SendMessage` on `/agents/{agent_id}`. operationId: RunAstralLiteSendMessage responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1SendMessageResponse" 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: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to send the message to. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceSendMessageBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral-lite/threads/{thread_id}/stream" : get: summary: Stream Thread Events (Astral Lite, run) description: |- Subscribe to thread events via SSE Opens a persistent SSE connection that streams all events for the specified thread. **Event Flow:** 1. Historical events are sent first (if the thread has existing events) 2. Live events are streamed as they occur (InputText, OutputText, ToolCall*, etc.) 3. Connection stays open until the client disconnects **SSE Message Format:** Each message contains a JSON-serialized `Event` object in the `data` field: ``` data: {"output_text":{"text":"Hello"}} data: {"generation_complete":{"usage":{"prompt_tokens":10,"completion_tokens":5}}} ``` **Extracting Events:** ```javascript const eventSource = new EventSource('/agents/my-agent/threads/my-thread/stream'); eventSource.onmessage = (e) => { const event = JSON.parse(e.data); if (event.output_text) { console.log('Output:', event.output_text.text); } }; ``` This is the browser-compatible alternative to the gRPC `SubscribeThread` RPC. Targets the built-in `astral-lite` agent in the run scope; the generic form is `StreamThreadEvents` on `/agents/{agent_id}`. operationId: RunAstralLiteStreamThreadEvents responses: "200": description: SSE stream of thread events content: text/event-stream: schema: type: string description: Server-sent events; each `data:` line is a JSON `agentsV1Event`. "404": description: Agent or thread not found parameters: - name: organization_id in: path required: true schema: type: string - name: workspace_id in: path required: true schema: type: string - name: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string - name: thread_id in: path description: The ID of the thread to subscribe to. required: true schema: type: string tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral-lite/threads/{thread_id}/sub-agents" : get: summary: List Sub Agents (Astral Lite, run) description: |- Lists sub-agents configured for a thread. Targets the built-in `astral-lite` agent in the run scope; the generic form is `ListSubAgents` on `/agents/{agent_id}`. operationId: RunAstralLiteListSubAgents responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1ListSubAgentsResponse" 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: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string - name: thread_id description: Required. The thread whose sub-agents to list. in: path required: true schema: type: string tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral-lite/threads/{thread_id}/tool-calls" : post: summary: Send Tool Call (Astral Lite, run) description: |- Injects a deterministic tool call into a thread. Appends an assistant-voice preamble announcing the call as an externally requested action, then a synthetic ToolCallStart (plus one ToolCallArgument per supplied argument) to the thread event log under the generation lock, executes the tool through the normal dispatcher, and continues with an LLM turn that has the tool result in context. The preamble keeps the model from misattributing the call to itself. Targets the built-in `astral-lite` agent in the run scope; the generic form is `SendToolCall` on `/agents/{agent_id}`. operationId: RunAstralLiteSendToolCall responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1SendToolCallResponse" 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: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to inject the call into. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceSendToolCallBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral-lite/threads/{thread_id}/tool-results" : post: summary: Send Tool Result (Astral Lite, run) description: |- Sends a tool execution result for a remote tool. Remote tools pause generation when called, waiting for an external system to execute them and return the result via this RPC. Generation resumes once the result is received. Targets the built-in `astral-lite` agent in the run scope; the generic form is `SendToolResult` on `/agents/{agent_id}`. operationId: RunAstralLiteSendToolResult responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1SendToolResultResponse" 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: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread where the remote tool was called. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceSendToolResultBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral-lite/threads/{thread_id}/uploads" : post: summary: Upload Thread File (Astral Lite, run) description: |- Upload a file to a thread Accepts a `multipart/form-data` body with a single `file` part and stores it for the thread under `uploads://`. Returns the artifact URI plus the recorded MIME type, byte size, and filename. The MIME type is taken from the part's `Content-Type` header when the browser supplies one, falls back to a guess based on the filename extension, and finally to `application/octet-stream`. Multipart parts other than `file` are accepted and ignored, leaving room for forward-compatible additions (e.g. a content hash, a TTL override) without breaking older servers. **Client example (browser, with progress):** ```javascript const form = new FormData(); form.append('file', file); const xhr = new XMLHttpRequest(); xhr.upload.onprogress = (e) => { if (e.lengthComputable) { console.log(`uploaded ${e.loaded} / ${e.total}`); } }; xhr.onload = () => { if (xhr.status === 200) { const { uri } = JSON.parse(xhr.responseText); // include `uri` in SendMessage.documents } }; xhr.open('POST', `/api/v1/agents/${agentId}/threads/${threadId}/uploads`); xhr.send(form); ``` Targets the built-in `astral-lite` agent in the run scope; the generic form is `UploadThreadFile` on `/agents/{agent_id}`. operationId: RunAstralLiteUploadThreadFile responses: "200": description: Upload accepted; artifact written to uploads://<filename>. content: application/json: schema: type: object required: - uri - mime_type - size - filename properties: uri: type: string description: Artifact URI to embed in SendMessage.documents. example: uploads://report.pdf mime_type: type: string description: MIME type recorded on the artifact. example: application/pdf size: type: integer format: int64 description: Size of the stored content in bytes. filename: type: string description: Filename the artifact is stored under within the uploads:// store. "400": description: Multipart body missing the `file` part, missing a filename, or otherwise malformed. "404": description: Agent or thread not found. "413": description: Payload too large (server body-size limit exceeded). "500": description: Internal store error. parameters: - name: organization_id in: path required: true schema: type: string - name: workspace_id in: path required: true schema: type: string - name: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string - name: thread_id in: path description: The ID of the thread the upload is staged into. required: true schema: type: string requestBody: required: true content: multipart/form-data: schema: type: object required: - file properties: file: type: string format: binary description: The file payload. The part's filename and Content-Type are recorded on the artifact. tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral-lite/threads/{thread_id}:compact" : post: summary: Compact Thread (Astral Lite, run) description: |- Starts context compaction for a thread. Compaction summarizes conversation history to reduce context size while preserving essential information. This RPC emits a CompactStart event and returns the compact_id for tracking. The actual compaction is performed asynchronously. Once complete, a CompactComplete event with the summary content should be added to the thread using the returned compact_id. While compaction is in progress (CompactStart without CompactComplete), the UI should block user input. Targets the built-in `astral-lite` agent in the run scope; the generic form is `CompactThread` on `/agents/{agent_id}`. operationId: RunAstralLiteCompactThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1StartCompactionResponse" 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: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to compact. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceStartCompactionBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral-lite/threads/{thread_id}:fork" : post: summary: Fork Thread (Astral Lite, run) description: |- Forks (duplicates) a thread with all its data. Creates a new thread that is a complete copy of the source thread, including events, feedback, memory customizations, scratchpad, plan, and template config customizations. Returns FAILED_PRECONDITION if the source thread is currently generating. Targets the built-in `astral-lite` agent in the run scope; the generic form is `ForkThread` on `/agents/{agent_id}`. operationId: RunAstralLiteForkThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Thread" 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: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string - name: thread_id description: Required. The source thread to fork. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceForkThreadBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral-lite/threads/{thread_id}:stop" : post: summary: Stop Thread (Astral Lite, run) description: |- Stops an in-progress generation in a thread. If a generation is currently running, it will be cancelled and a GenerationFailed event with STOPPED kind will be emitted. If no generation is in progress, this is a no-op and returns stopped=false. Targets the built-in `astral-lite` agent in the run scope; the generic form is `StopThread` on `/agents/{agent_id}`. operationId: RunAstralLiteStopThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1StopResponse" 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: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread with the generation to stop. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceStopBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral-lite/threads/{thread_id}:wake" : post: summary: Wake Thread (Astral Lite, run) description: |- Wakes a thread that is currently sleeping (UI "Wake up" button). Atomically ends the pending sleep with `interrupted_by_user = true`, cancels the scheduled wake task, and triggers a new generation so the LLM observes the early return in its rebuilt history. No-op when no sleep is pending; the call still triggers a normal Reminder-driven resume in that case. Targets the built-in `astral-lite` agent in the run scope; the generic form is `WakeThread` on `/agents/{agent_id}`. operationId: RunAstralLiteWakeThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1WakeResponse" 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: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the sleeping thread to wake. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceWakeBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral2/threads" : get: summary: List Threads (Astral2, run) description: |- Lists all threads for an agent. Targets the built-in `astral2` agent in the run scope; the generic form is `ListThreads` on `/agents/{agent_id}`. operationId: RunAstral2ListThreads responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1ListThreadsResponse" 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: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string - name: filter description: |- Optional REL expression filtering over thread fields. Empty = no filter. Supported fields: agent_id (string) status (string, snake_case discriminant) variables., metadata. (string) title, description (optional string) created_at, updated_at (RFC-3339 string literal) agent_version (integer) origin.kind (string: "schedule" / "sub_agent") origin.schedule.schedule_id (string) origin.sub_agent.parent_agent_id (string) origin.sub_agent.parent_thread_id (string) origin.sub_agent.task_id (string) hydration (string: "hydrated" / "dehydrated") Examples: variables.region == "us-east" && updated_at >= "2026-05-01T00:00:00Z" title.contains("invoice") agent_version in [3, 4, 5] origin.kind == "schedule" has(origin.sub_agent.parent_agent_id) in: query required: false schema: type: string tags: - Agents post: summary: Create Thread (Astral2, run) description: |- Creates a new thread. The thread_id is auto-generated. Optionally provide a title and description. Targets the built-in `astral2` agent in the run scope; the generic form is `CreateThread` on `/agents/{agent_id}`. operationId: RunAstral2CreateThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Thread" 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: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceCreateThreadBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral2/threads/{thread_id}" : get: summary: Get Thread (Astral2, run) description: |- Gets a thread by ID. Returns thread metadata and event count without loading the full event history. Returns NOT_FOUND if the thread doesn't exist. Targets the built-in `astral2` agent in the run scope; the generic form is `GetThread` on `/agents/{agent_id}`. operationId: RunAstral2GetThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Thread" 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: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to retrieve. in: path required: true schema: type: string tags: - Agents patch: summary: Update Thread (Astral2, run) description: |- Updates a thread's title and/or description. Targets the built-in `astral2` agent in the run scope; the generic form is `UpdateThread` on `/agents/{agent_id}`. operationId: RunAstral2UpdateThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Thread" 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: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to update. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceUpdateThreadBody" required: true tags: - Agents delete: summary: Delete Thread (Astral2, run) description: |- Deletes a thread and all its events. Targets the built-in `astral2` agent in the run scope; the generic form is `DeleteThread` on `/agents/{agent_id}`. operationId: RunAstral2DeleteThread responses: "204": description: No content. 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: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to delete. in: path required: true schema: type: string tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral2/threads/{thread_id}/context" : get: summary: Get Thread Context (Astral2, run) description: |- Gets thread context information including all context items with token counts. Returns a unified view of all items contributing to the context window: - Memory blocks (fixed and volatile) - Enabled tools (fixed) - Conversation history (compactable) Each item includes its token count for context budget management. Targets the built-in `astral2` agent in the run scope; the generic form is `GetThreadContext` on `/agents/{agent_id}`. operationId: RunAstral2GetThreadContext responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1GetThreadContextResponse" 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: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string - name: thread_id description: The thread ID. in: path required: true schema: type: string tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral2/threads/{thread_id}/events" : get: summary: Get Thread Events (Astral2, run) description: |- Retrieves all events from a thread. This RPC returns the complete history of events for a thread, including user inputs, assistant responses, tool calls, and their results. Events are returned in chronological order. Targets the built-in `astral2` agent in the run scope; the generic form is `GetThreadEvents` on `/agents/{agent_id}`. operationId: RunAstral2GetThreadEvents responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1GetEventsResponse" 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: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to retrieve events from. in: path required: true schema: type: string - name: compacted description: |- Optional. If true, return the compacted view of events. The compacted view shows what the LLM sees: events in compacted ranges are excluded and replaced by CompactComplete events containing summaries. If false (default), returns the full event history for UI display. in: query required: false schema: type: boolean - name: include_deleted description: |- Optional. If true, include deleted events in the response. Deleted events will have the `deleted` field set to true on each event. in: query required: false schema: type: boolean tags: - Agents post: summary: Send Message And Wait (Astral2, run) description: |- Sends a message and streams back response events synchronously. This RPC adds user input to the specified thread and returns a stream of events representing the assistant's response. Events include output text, tool calls, and completion metadata. Targets the built-in `astral2` agent in the run scope; the generic form is `SendMessageAndWait` on `/agents/{agent_id}`. operationId: RunAstral2SendMessageAndWait responses: "200": description: A successful response.(streaming responses) content: application/json: schema: type: object properties: result: $ref: "#/components/schemas/agentsV1Event" error: $ref: "#/components/schemas/rpcStatus" title: Stream result of v1Event 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: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to send the message to. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceSendMessageSyncBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral2/threads/{thread_id}/feedback" : post: summary: Set Thread Feedback (Astral2, run) description: |- Sets feedback (like/dislike) for a generation response. Feedback is mutually exclusive - setting LIKE removes any DISLIKE and vice versa. Setting the same feedback that already exists is a no-op. Use FEEDBACK_TYPE_UNSPECIFIED to clear existing feedback. Feedback is stored with the thread and is purely for analytics/UI purposes. It is not visible to the LLM. Targets the built-in `astral2` agent in the run scope; the generic form is `SetThreadFeedback` on `/agents/{agent_id}`. operationId: RunAstral2SetThreadFeedback responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1SetFeedbackResponse" 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: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread containing the generation. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceSetFeedbackBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral2/threads/{thread_id}/input" : post: summary: Send Message (Astral2, run) description: |- Sends a message to a thread (fire and forget). The message is added to the thread and generation begins asynchronously. Response events arrive via SubscribeThread stream or SSE, not this RPC. Targets the built-in `astral2` agent in the run scope; the generic form is `SendMessage` on `/agents/{agent_id}`. operationId: RunAstral2SendMessage responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1SendMessageResponse" 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: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to send the message to. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceSendMessageBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral2/threads/{thread_id}/stream" : get: summary: Stream Thread Events (Astral2, run) description: |- Subscribe to thread events via SSE Opens a persistent SSE connection that streams all events for the specified thread. **Event Flow:** 1. Historical events are sent first (if the thread has existing events) 2. Live events are streamed as they occur (InputText, OutputText, ToolCall*, etc.) 3. Connection stays open until the client disconnects **SSE Message Format:** Each message contains a JSON-serialized `Event` object in the `data` field: ``` data: {"output_text":{"text":"Hello"}} data: {"generation_complete":{"usage":{"prompt_tokens":10,"completion_tokens":5}}} ``` **Extracting Events:** ```javascript const eventSource = new EventSource('/agents/my-agent/threads/my-thread/stream'); eventSource.onmessage = (e) => { const event = JSON.parse(e.data); if (event.output_text) { console.log('Output:', event.output_text.text); } }; ``` This is the browser-compatible alternative to the gRPC `SubscribeThread` RPC. Targets the built-in `astral2` agent in the run scope; the generic form is `StreamThreadEvents` on `/agents/{agent_id}`. operationId: RunAstral2StreamThreadEvents responses: "200": description: SSE stream of thread events content: text/event-stream: schema: type: string description: Server-sent events; each `data:` line is a JSON `agentsV1Event`. "404": description: Agent or thread not found parameters: - name: organization_id in: path required: true schema: type: string - name: workspace_id in: path required: true schema: type: string - name: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string - name: thread_id in: path description: The ID of the thread to subscribe to. required: true schema: type: string tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral2/threads/{thread_id}/sub-agents" : get: summary: List Sub Agents (Astral2, run) description: |- Lists sub-agents configured for a thread. Targets the built-in `astral2` agent in the run scope; the generic form is `ListSubAgents` on `/agents/{agent_id}`. operationId: RunAstral2ListSubAgents responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1ListSubAgentsResponse" 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: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string - name: thread_id description: Required. The thread whose sub-agents to list. in: path required: true schema: type: string tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral2/threads/{thread_id}/tool-calls" : post: summary: Send Tool Call (Astral2, run) description: |- Injects a deterministic tool call into a thread. Appends an assistant-voice preamble announcing the call as an externally requested action, then a synthetic ToolCallStart (plus one ToolCallArgument per supplied argument) to the thread event log under the generation lock, executes the tool through the normal dispatcher, and continues with an LLM turn that has the tool result in context. The preamble keeps the model from misattributing the call to itself. Targets the built-in `astral2` agent in the run scope; the generic form is `SendToolCall` on `/agents/{agent_id}`. operationId: RunAstral2SendToolCall responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1SendToolCallResponse" 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: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to inject the call into. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceSendToolCallBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral2/threads/{thread_id}/tool-results" : post: summary: Send Tool Result (Astral2, run) description: |- Sends a tool execution result for a remote tool. Remote tools pause generation when called, waiting for an external system to execute them and return the result via this RPC. Generation resumes once the result is received. Targets the built-in `astral2` agent in the run scope; the generic form is `SendToolResult` on `/agents/{agent_id}`. operationId: RunAstral2SendToolResult responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1SendToolResultResponse" 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: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread where the remote tool was called. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceSendToolResultBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral2/threads/{thread_id}/uploads" : post: summary: Upload Thread File (Astral2, run) description: |- Upload a file to a thread Accepts a `multipart/form-data` body with a single `file` part and stores it for the thread under `uploads://`. Returns the artifact URI plus the recorded MIME type, byte size, and filename. The MIME type is taken from the part's `Content-Type` header when the browser supplies one, falls back to a guess based on the filename extension, and finally to `application/octet-stream`. Multipart parts other than `file` are accepted and ignored, leaving room for forward-compatible additions (e.g. a content hash, a TTL override) without breaking older servers. **Client example (browser, with progress):** ```javascript const form = new FormData(); form.append('file', file); const xhr = new XMLHttpRequest(); xhr.upload.onprogress = (e) => { if (e.lengthComputable) { console.log(`uploaded ${e.loaded} / ${e.total}`); } }; xhr.onload = () => { if (xhr.status === 200) { const { uri } = JSON.parse(xhr.responseText); // include `uri` in SendMessage.documents } }; xhr.open('POST', `/api/v1/agents/${agentId}/threads/${threadId}/uploads`); xhr.send(form); ``` Targets the built-in `astral2` agent in the run scope; the generic form is `UploadThreadFile` on `/agents/{agent_id}`. operationId: RunAstral2UploadThreadFile responses: "200": description: Upload accepted; artifact written to uploads://<filename>. content: application/json: schema: type: object required: - uri - mime_type - size - filename properties: uri: type: string description: Artifact URI to embed in SendMessage.documents. example: uploads://report.pdf mime_type: type: string description: MIME type recorded on the artifact. example: application/pdf size: type: integer format: int64 description: Size of the stored content in bytes. filename: type: string description: Filename the artifact is stored under within the uploads:// store. "400": description: Multipart body missing the `file` part, missing a filename, or otherwise malformed. "404": description: Agent or thread not found. "413": description: Payload too large (server body-size limit exceeded). "500": description: Internal store error. parameters: - name: organization_id in: path required: true schema: type: string - name: workspace_id in: path required: true schema: type: string - name: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string - name: thread_id in: path description: The ID of the thread the upload is staged into. required: true schema: type: string requestBody: required: true content: multipart/form-data: schema: type: object required: - file properties: file: type: string format: binary description: The file payload. The part's filename and Content-Type are recorded on the artifact. tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral2/threads/{thread_id}:compact" : post: summary: Compact Thread (Astral2, run) description: |- Starts context compaction for a thread. Compaction summarizes conversation history to reduce context size while preserving essential information. This RPC emits a CompactStart event and returns the compact_id for tracking. The actual compaction is performed asynchronously. Once complete, a CompactComplete event with the summary content should be added to the thread using the returned compact_id. While compaction is in progress (CompactStart without CompactComplete), the UI should block user input. Targets the built-in `astral2` agent in the run scope; the generic form is `CompactThread` on `/agents/{agent_id}`. operationId: RunAstral2CompactThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1StartCompactionResponse" 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: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to compact. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceStartCompactionBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral2/threads/{thread_id}:fork" : post: summary: Fork Thread (Astral2, run) description: |- Forks (duplicates) a thread with all its data. Creates a new thread that is a complete copy of the source thread, including events, feedback, memory customizations, scratchpad, plan, and template config customizations. Returns FAILED_PRECONDITION if the source thread is currently generating. Targets the built-in `astral2` agent in the run scope; the generic form is `ForkThread` on `/agents/{agent_id}`. operationId: RunAstral2ForkThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Thread" 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: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string - name: thread_id description: Required. The source thread to fork. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceForkThreadBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral2/threads/{thread_id}:stop" : post: summary: Stop Thread (Astral2, run) description: |- Stops an in-progress generation in a thread. If a generation is currently running, it will be cancelled and a GenerationFailed event with STOPPED kind will be emitted. If no generation is in progress, this is a no-op and returns stopped=false. Targets the built-in `astral2` agent in the run scope; the generic form is `StopThread` on `/agents/{agent_id}`. operationId: RunAstral2StopThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1StopResponse" 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: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread with the generation to stop. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceStopBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral2/threads/{thread_id}:wake" : post: summary: Wake Thread (Astral2, run) description: |- Wakes a thread that is currently sleeping (UI "Wake up" button). Atomically ends the pending sleep with `interrupted_by_user = true`, cancels the scheduled wake task, and triggers a new generation so the LLM observes the early return in its rebuilt history. No-op when no sleep is pending; the call still triggers a normal Reminder-driven resume in that case. Targets the built-in `astral2` agent in the run scope; the generic form is `WakeThread` on `/agents/{agent_id}`. operationId: RunAstral2WakeThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1WakeResponse" 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: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the sleeping thread to wake. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceWakeBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/versions/{book_version}/agents/shifu/threads" : post: summary: Create Thread (Shifu, book version) description: |- Creates a new thread. The thread_id is auto-generated. Optionally provide a title and description. Targets the built-in `shifu` agent in the book version scope; the generic form is `CreateThread` on `/agents/{agent_id}`. operationId: BookShifuCreateThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Thread" 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: book_name in: path required: true schema: type: string - name: book_version in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceCreateThreadBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/versions/{book_version}/agents/shifu/threads/{thread_id}" : delete: summary: Delete Thread (Shifu, book version) description: |- Deletes a thread and all its events. Targets the built-in `shifu` agent in the book version scope; the generic form is `DeleteThread` on `/agents/{agent_id}`. operationId: BookShifuDeleteThread responses: "204": description: No content. 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: book_name in: path required: true schema: type: string - name: book_version in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to delete. in: path required: true schema: type: string tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/versions/{book_version}/agents/shifu/threads/{thread_id}/input" : post: summary: Send Message (Shifu, book version) description: |- Sends a message to a thread (fire and forget). The message is added to the thread and generation begins asynchronously. Response events arrive via SubscribeThread stream or SSE, not this RPC. Targets the built-in `shifu` agent in the book version scope; the generic form is `SendMessage` on `/agents/{agent_id}`. operationId: BookShifuSendMessage responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1SendMessageResponse" 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: book_name in: path required: true schema: type: string - name: book_version in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to send the message to. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceSendMessageBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/versions/{book_version}/agents/shifu/threads/{thread_id}/stream" : get: summary: Stream Thread Events (Shifu, book version) description: |- Subscribe to thread events via SSE Opens a persistent SSE connection that streams all events for the specified thread. **Event Flow:** 1. Historical events are sent first (if the thread has existing events) 2. Live events are streamed as they occur (InputText, OutputText, ToolCall*, etc.) 3. Connection stays open until the client disconnects **SSE Message Format:** Each message contains a JSON-serialized `Event` object in the `data` field: ``` data: {"output_text":{"text":"Hello"}} data: {"generation_complete":{"usage":{"prompt_tokens":10,"completion_tokens":5}}} ``` **Extracting Events:** ```javascript const eventSource = new EventSource('/agents/my-agent/threads/my-thread/stream'); eventSource.onmessage = (e) => { const event = JSON.parse(e.data); if (event.output_text) { console.log('Output:', event.output_text.text); } }; ``` This is the browser-compatible alternative to the gRPC `SubscribeThread` RPC. Targets the built-in `shifu` agent in the book version scope; the generic form is `StreamThreadEvents` on `/agents/{agent_id}`. operationId: BookShifuStreamThreadEvents responses: "200": description: SSE stream of thread events content: text/event-stream: schema: type: string description: Server-sent events; each `data:` line is a JSON `agentsV1Event`. "404": description: Agent or thread not found parameters: - name: organization_id in: path required: true schema: type: string - name: workspace_id in: path required: true schema: type: string - name: book_name in: path required: true schema: type: string - name: book_version in: path required: true schema: type: string - name: thread_id in: path description: The ID of the thread to subscribe to. required: true schema: type: string tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/versions/{book_version}/authentications/{selected_authentication_id}/agents/shifu/threads" : post: summary: Create Thread (Shifu, book authentication) description: |- Creates a new thread. The thread_id is auto-generated. Optionally provide a title and description. Targets the built-in `shifu` agent in the book authentication scope; the generic form is `CreateThread` on `/agents/{agent_id}`. operationId: BookAuthenticationShifuCreateThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Thread" 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: book_name in: path required: true schema: type: string - name: book_version in: path required: true schema: type: string - name: selected_authentication_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceCreateThreadBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/versions/{book_version}/authentications/{selected_authentication_id}/agents/shifu/threads/{thread_id}" : delete: summary: Delete Thread (Shifu, book authentication) description: |- Deletes a thread and all its events. Targets the built-in `shifu` agent in the book authentication scope; the generic form is `DeleteThread` on `/agents/{agent_id}`. operationId: BookAuthenticationShifuDeleteThread responses: "204": description: No content. 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: book_name in: path required: true schema: type: string - name: book_version in: path required: true schema: type: string - name: selected_authentication_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to delete. in: path required: true schema: type: string tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/versions/{book_version}/authentications/{selected_authentication_id}/agents/shifu/threads/{thread_id}/input" : post: summary: Send Message (Shifu, book authentication) description: |- Sends a message to a thread (fire and forget). The message is added to the thread and generation begins asynchronously. Response events arrive via SubscribeThread stream or SSE, not this RPC. Targets the built-in `shifu` agent in the book authentication scope; the generic form is `SendMessage` on `/agents/{agent_id}`. operationId: BookAuthenticationShifuSendMessage responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1SendMessageResponse" 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: book_name in: path required: true schema: type: string - name: book_version in: path required: true schema: type: string - name: selected_authentication_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to send the message to. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceSendMessageBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/versions/{book_version}/authentications/{selected_authentication_id}/agents/shifu/threads/{thread_id}/stream" : get: summary: Stream Thread Events (Shifu, book authentication) description: |- Subscribe to thread events via SSE Opens a persistent SSE connection that streams all events for the specified thread. **Event Flow:** 1. Historical events are sent first (if the thread has existing events) 2. Live events are streamed as they occur (InputText, OutputText, ToolCall*, etc.) 3. Connection stays open until the client disconnects **SSE Message Format:** Each message contains a JSON-serialized `Event` object in the `data` field: ``` data: {"output_text":{"text":"Hello"}} data: {"generation_complete":{"usage":{"prompt_tokens":10,"completion_tokens":5}}} ``` **Extracting Events:** ```javascript const eventSource = new EventSource('/agents/my-agent/threads/my-thread/stream'); eventSource.onmessage = (e) => { const event = JSON.parse(e.data); if (event.output_text) { console.log('Output:', event.output_text.text); } }; ``` This is the browser-compatible alternative to the gRPC `SubscribeThread` RPC. Targets the built-in `shifu` agent in the book authentication scope; the generic form is `StreamThreadEvents` on `/agents/{agent_id}`. operationId: BookAuthenticationShifuStreamThreadEvents responses: "200": description: SSE stream of thread events content: text/event-stream: schema: type: string description: Server-sent events; each `data:` line is a JSON `agentsV1Event`. "404": description: Agent or thread not found parameters: - name: organization_id in: path required: true schema: type: string - name: workspace_id in: path required: true schema: type: string - name: book_name in: path required: true schema: type: string - name: book_version in: path required: true schema: type: string - name: selected_authentication_id in: path required: true schema: type: string - name: thread_id in: path description: The ID of the thread to subscribe to. required: true schema: type: string tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/versions/{book_version}/connections/{connection_id}/agents/shifu/threads" : get: summary: List Threads (Shifu, book connection) description: |- Lists all threads for an agent. Targets the built-in `shifu` agent in the book connection scope; the generic form is `ListThreads` on `/agents/{agent_id}`. operationId: BookConnectionShifuListThreads responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1ListThreadsResponse" 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: book_name in: path required: true schema: type: string - name: book_version in: path required: true schema: type: string - name: connection_id in: path required: true schema: type: string - name: filter description: |- Optional REL expression filtering over thread fields. Empty = no filter. Supported fields: agent_id (string) status (string, snake_case discriminant) variables., metadata. (string) title, description (optional string) created_at, updated_at (RFC-3339 string literal) agent_version (integer) origin.kind (string: "schedule" / "sub_agent") origin.schedule.schedule_id (string) origin.sub_agent.parent_agent_id (string) origin.sub_agent.parent_thread_id (string) origin.sub_agent.task_id (string) hydration (string: "hydrated" / "dehydrated") Examples: variables.region == "us-east" && updated_at >= "2026-05-01T00:00:00Z" title.contains("invoice") agent_version in [3, 4, 5] origin.kind == "schedule" has(origin.sub_agent.parent_agent_id) in: query required: false schema: type: string tags: - Agents post: summary: Create Thread (Shifu, book connection) description: |- Creates a new thread. The thread_id is auto-generated. Optionally provide a title and description. Targets the built-in `shifu` agent in the book connection scope; the generic form is `CreateThread` on `/agents/{agent_id}`. operationId: BookConnectionShifuCreateThread responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1Thread" 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: book_name in: path required: true schema: type: string - name: book_version in: path required: true schema: type: string - name: connection_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceCreateThreadBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/versions/{book_version}/connections/{connection_id}/agents/shifu/threads/{thread_id}" : delete: summary: Delete Thread (Shifu, book connection) description: |- Deletes a thread and all its events. Targets the built-in `shifu` agent in the book connection scope; the generic form is `DeleteThread` on `/agents/{agent_id}`. operationId: BookConnectionShifuDeleteThread responses: "204": description: No content. 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: book_name in: path required: true schema: type: string - name: book_version in: path required: true schema: type: string - name: connection_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to delete. in: path required: true schema: type: string tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/versions/{book_version}/connections/{connection_id}/agents/shifu/threads/{thread_id}/events" : get: summary: Get Thread Events (Shifu, book connection) description: |- Retrieves all events from a thread. This RPC returns the complete history of events for a thread, including user inputs, assistant responses, tool calls, and their results. Events are returned in chronological order. Targets the built-in `shifu` agent in the book connection scope; the generic form is `GetThreadEvents` on `/agents/{agent_id}`. operationId: BookConnectionShifuGetThreadEvents responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1GetEventsResponse" 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: book_name in: path required: true schema: type: string - name: book_version in: path required: true schema: type: string - name: connection_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to retrieve events from. in: path required: true schema: type: string - name: compacted description: |- Optional. If true, return the compacted view of events. The compacted view shows what the LLM sees: events in compacted ranges are excluded and replaced by CompactComplete events containing summaries. If false (default), returns the full event history for UI display. in: query required: false schema: type: boolean - name: include_deleted description: |- Optional. If true, include deleted events in the response. Deleted events will have the `deleted` field set to true on each event. in: query required: false schema: type: boolean tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/versions/{book_version}/connections/{connection_id}/agents/shifu/threads/{thread_id}/input" : post: summary: Send Message (Shifu, book connection) description: |- Sends a message to a thread (fire and forget). The message is added to the thread and generation begins asynchronously. Response events arrive via SubscribeThread stream or SSE, not this RPC. Targets the built-in `shifu` agent in the book connection scope; the generic form is `SendMessage` on `/agents/{agent_id}`. operationId: BookConnectionShifuSendMessage responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1SendMessageResponse" 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: book_name in: path required: true schema: type: string - name: book_version in: path required: true schema: type: string - name: connection_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread to send the message to. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceSendMessageBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/versions/{book_version}/connections/{connection_id}/agents/shifu/threads/{thread_id}/stream" : get: summary: Stream Thread Events (Shifu, book connection) description: |- Subscribe to thread events via SSE Opens a persistent SSE connection that streams all events for the specified thread. **Event Flow:** 1. Historical events are sent first (if the thread has existing events) 2. Live events are streamed as they occur (InputText, OutputText, ToolCall*, etc.) 3. Connection stays open until the client disconnects **SSE Message Format:** Each message contains a JSON-serialized `Event` object in the `data` field: ``` data: {"output_text":{"text":"Hello"}} data: {"generation_complete":{"usage":{"prompt_tokens":10,"completion_tokens":5}}} ``` **Extracting Events:** ```javascript const eventSource = new EventSource('/agents/my-agent/threads/my-thread/stream'); eventSource.onmessage = (e) => { const event = JSON.parse(e.data); if (event.output_text) { console.log('Output:', event.output_text.text); } }; ``` This is the browser-compatible alternative to the gRPC `SubscribeThread` RPC. Targets the built-in `shifu` agent in the book connection scope; the generic form is `StreamThreadEvents` on `/agents/{agent_id}`. operationId: BookConnectionShifuStreamThreadEvents responses: "200": description: SSE stream of thread events content: text/event-stream: schema: type: string description: Server-sent events; each `data:` line is a JSON `agentsV1Event`. "404": description: Agent or thread not found parameters: - name: organization_id in: path required: true schema: type: string - name: workspace_id in: path required: true schema: type: string - name: book_name in: path required: true schema: type: string - name: book_version in: path required: true schema: type: string - name: connection_id in: path required: true schema: type: string - name: thread_id in: path description: The ID of the thread to subscribe to. required: true schema: type: string tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/versions/{book_version}/connections/{connection_id}/agents/shifu/threads/{thread_id}/tool-results" : post: summary: Send Tool Result (Shifu, book connection) description: |- Sends a tool execution result for a remote tool. Remote tools pause generation when called, waiting for an external system to execute them and return the result via this RPC. Generation resumes once the result is received. Targets the built-in `shifu` agent in the book connection scope; the generic form is `SendToolResult` on `/agents/{agent_id}`. operationId: BookConnectionShifuSendToolResult responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1SendToolResultResponse" 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: book_name in: path required: true schema: type: string - name: book_version in: path required: true schema: type: string - name: connection_id in: path required: true schema: type: string - name: thread_id description: Required. The ID of the thread where the remote tool was called. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsThreadServiceSendToolResultBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/versions/{book_version}/connections/{connection_id}/agents/shifu/threads/{thread_id}/tool-sources" : post: summary: Create Tool Source (Shifu, book connection) description: |- Creates a new tool source for a thread. Targets the built-in `shifu` agent in the book connection scope; the generic form is `CreateToolSource` on `/agents/{agent_id}`. operationId: BookConnectionShifuCreateToolSource responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1ToolSource" 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: book_name in: path required: true schema: type: string - name: book_version in: path required: true schema: type: string - name: connection_id in: path required: true schema: type: string - name: thread_id description: Required. The thread that owns this resource. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsToolCatalogServiceCreateToolSourceBody" required: true tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/versions/{book_version}/connections/{connection_id}/agents/shifu/threads/{thread_id}/tools" : get: summary: List Tools (Shifu, book connection) description: |- Lists the flat tool catalog for a thread (one entry per enabled tool across all sources). Reflects per-thread enablement and adapter overrides; the agent's read-only base catalog is exposed by `DiffTools.base`. Targets the built-in `shifu` agent in the book connection scope; the generic form is `ListTools` on `/agents/{agent_id}`. operationId: BookConnectionShifuListTools responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1ListToolsResponse" 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: book_name in: path required: true schema: type: string - name: book_version in: path required: true schema: type: string - name: connection_id in: path required: true schema: type: string - name: thread_id description: Required. The thread context for variable resolution. in: path required: true schema: type: string - name: source_id description: Optional. Filter by source ID. in: query required: false schema: type: string - name: name_query description: Optional. Search query for tool name (case-insensitive contains). in: query required: false schema: type: string - name: description_query description: Optional. Search query for tool description (case-insensitive contains). in: query required: false schema: type: string tags: - Agents ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/versions/{book_version}/connections/{connection_id}/agents/shifu/threads/{thread_id}/tools/{tool_source_id}:enable" : post: summary: Enable Tools (Shifu, book connection) description: |- Enables multiple tools in a source on a thread (additive). Targets the built-in `shifu` agent in the book connection scope; the generic form is `EnableTools` on `/agents/{agent_id}`. operationId: BookConnectionShifuEnableTools responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/agentsV1ToolEnablement" 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: book_name in: path required: true schema: type: string - name: book_version in: path required: true schema: type: string - name: connection_id in: path required: true schema: type: string - name: thread_id description: Required. The thread that owns this resource. in: path required: true schema: type: string - name: tool_source_id description: Required. The source ID containing the tools. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/agentsToolCatalogServiceEnableToolsBody" required: true tags: - Agents "/api/v1/me": get: summary: Current User description: |- Gets the current authenticated user. This is a singleton resource that represents the currently authenticated user. operationId: CurrentUser responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1CurrentUserResponse" default: description: An unexpected error response. content: application/json: schema: $ref: "#/components/schemas/rpcStatus" tags: - Organizations "/api/v1/me/organizations/{organization_id}/roles": get: summary: Current User Organization Roles description: Returns the current authenticated user's roles in an organization. operationId: CurrentUserOrganizationRoles responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1CurrentUserOrganizationRolesResponse" 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 tags: - Organizations "/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 "/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. 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. 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 always returned in a single response. Both client uses — building a lookup map to label a role's permissions, and populating a custom-role picker — need the whole catalog before they can render anything, so paging would only force every caller into a fetch loop. The catalog is a small, static, cacheable set. If it ever grows enough to need 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 "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agentBundles/{agent_id}:export": post: summary: Export Agent description: |- Exports an agent (optionally a specific version) together with the automations it references as a single ZIP bundle. Uploads the bundle to file storage and returns a ~1-hour presigned download URL. SPy code files inside the bundled automations are encrypted at rest within the bundle. Only the latest published revision of each referenced automation is bundled; drafts are never exported. The agent's attached automations and connections are read from the agent's effective tool catalog — its enabled `automations` and `connection` tool sources — so an automation that merely lives in the same workspace is not included. When the agent has no automations attached, the export still succeeds: the result is an agent-only bundle and a warning is returned in `warnings`. The export deliberately does NOT fall back to bundling every published automation in the workspace. Export is tolerant of incomplete source state: an automation that references a connection no longer present in the workspace is still bundled, with that connection alias omitted and a warning returned in `warnings`. A missing connection does not fail the export — the alias is reported again by ValidateAgentImport at the destination so it can be wired up there. Fails with FAILED_PRECONDITION if the encryption key is not configured. operationId: ExportWorkspaceAgent responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ExportAgentResponse" 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: agent_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/AgentImportExportServiceExportAgentBody" required: true tags: - Automations "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agentBundles/{agent_id}:validateImport": post: summary: Validate Agent Import description: |- Validates an agent that may have been created via import. Reports whether the agent was imported and, if so, what is still missing across its bundled automations before they can run: connections that have no match in the workspace and trigger kinds that are not yet configured. Read-only; makes no changes. operationId: ValidateAgentImport responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ValidateAgentImportResponse" 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: agent_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/AgentImportExportServiceValidateAgentImportBody" required: true tags: - Automations "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agentBundles:import": post: summary: Import Agent description: |- Imports an exported agent ZIP bundle into a workspace. Every bundled automation is recreated as a new draft 0.1, the newly created identifiers are rewritten into the agent template YAML, and the agent is then created in the target workspace. The operation is all-or-nothing: if any resource fails to be created, everything created so far is rolled back. Import always CREATES; it never updates an existing agent. The imported agent is assigned a freshly minted id, distinct from the id it had in the source workspace, and each bundled sub-agent is likewise created under a fresh id. Consequently: - the returned `agent` never names a pre-existing agent, and importing a bundle can never overwrite, version over, or delete one; - importing the same bundle twice — including back into the workspace it was exported from — yields two independent agents; - the source agent id is retained only as provenance, and is reported by ValidateAgentImport rather than reused as an identifier. Callers that want to replace an agent should delete it and import again. Fails with FAILED_PRECONDITION if the encryption key is not configured. Fails with INVALID_ARGUMENT if the bundle is malformed or decryption fails. operationId: ImportWorkspaceAgent responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ImportAgentResponse" 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 requestBody: content: application/json: schema: $ref: "#/components/schemas/AgentImportExportServiceImportAgentBody" required: true tags: - Automations "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/drafts": delete: summary: Delete Draft Automation description: |- DeleteDraftAutomation deletes draft versions of an automation. This endpoint specifically targets draft automations and will fail if the automation is not in DRAFT state. operationId: DeleteDraftAutomation responses: "200": description: A successful response. content: application/json: schema: type: object properties: {} 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: automation_id in: path required: true schema: type: string - name: force description: |- If set to true, any child resources will also be deleted. If set to false and the automation has child resources, the delete will fail. Per AIP-135, this field is required for resources with children. in: query required: false schema: type: boolean tags: - Automations "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/promotedParams": post: summary: Promote Params To Code description: |- PromoteParamsToCode writes tuned params back into the automation's draft SPy source at their value-slot locations (inline literal or a constant's definition), committing a new draft version. The adopt-the-winner step. Per AIP-136, a custom method (:promoteParamsToCode). operationId: PromoteParamsToCode responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1PromoteParamsToCodeResponse" 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: automation_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/AutomationServicePromoteParamsToCodeBody" required: true tags: - Automations "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/revisions:listSummaries": get: summary: List Automation Revision Summaries description: |- ListAutomationRevisionSummaries returns a paginated list of lightweight revision summaries for a specific automation. It mirrors ListAutomationRevisions but omits the heavy `code` (SPy) and `description` fields from each revision's snapshot, keeping responses small enough for version-history list views and avoiding oversized responses that exceed the API gateway's gRPC-JSON transcoding buffer. Revisions are returned in reverse chronological order (newest first) by default. operationId: ListAutomationRevisionSummaries responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ListAutomationRevisionSummariesResponse" 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: automation_id in: path required: true schema: type: string - name: page_size description: |- The maximum number of revision summaries to return in a single response. The service may return fewer than this value. If unspecified, at most 50 revision summaries 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 `ListAutomationRevisionSummaries` call. Provide this to retrieve the subsequent page of results. in: query required: false schema: type: string - name: filter description: |- Filter expression to restrict results. Per AIP-160, this should be a filtering expression following the Common Expression Language (CEL) syntax. Supported fields for filtering: - `stage`: The automation revision stage (e.g., DRAFT, PUBLISHED) Example filters: - `stage = "DRAFT"` - Returns only draft revisions - `stage = "PUBLISHED"` - Returns only published revisions If not specified or passed null, all revision summaries will be returned for that automation. in: query required: false schema: type: string tags: - Automations "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/stepConfig": get: summary: Inspect Step Config description: |- InspectStepConfig reads the current candidate/tuned overlay for an automation stage. Read-only. Per AIP-136, a custom method (:inspectStepConfig) — not a standard AIP-131 Get: there is no standalone StepConfig resource, and the overlay is addressed by parent automation + stage. operationId: InspectStepConfig responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1InspectStepConfigResponse" 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: automation_id in: path required: true schema: type: string - name: stage description: |- Stage to read. - AUTOMATION_STAGE_UNSPECIFIED: Automation stage is not specified. - AUTOMATION_STAGE_DRAFT: Automation is in draft stage and can be modified. - AUTOMATION_STAGE_PUBLISHED: Automation is published and immutable, ready for execution. in: query required: true schema: type: string enum: - AUTOMATION_STAGE_UNSPECIFIED - AUTOMATION_STAGE_DRAFT - AUTOMATION_STAGE_PUBLISHED default: AUTOMATION_STAGE_UNSPECIFIED tags: - Automations post: summary: Tune Step Config description: |- TuneStepConfig upserts candidate/tuned value-slot values for an automation's DRAFT — the durable store behind uncommitted step testing. Keys are ValueSlot.path (from IdentifyStepValueSlots). Values present are upserted; a value of NullValue clears that key. These are applied at run time (via the Jarvis arg-override, surfaced through BuildStepHarness.tunable_slots) without editing source; PromoteParamsToCode bakes the winner into code. Per AIP-136, a custom method (:tuneStepConfig). operationId: TuneStepConfig responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1TuneStepConfigResponse" 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: automation_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/AutomationServiceTuneStepConfigBody" required: true tags: - Automations "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/stepHarness": get: summary: Build Step Harness description: |- BuildStepHarness generates an "options-as-input" wrapper for a step so it can be run live over multiple inputs (via alfred's step evals) without editing the real automation: the chosen value slots become harness parameters. Read-only. Per AIP-136, a custom method (:buildStepHarness). operationId: BuildStepHarness responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1BuildStepHarnessResponse" 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: automation_id in: path required: true schema: type: string - name: stage description: |- Which stage's code to wrap (DRAFT or PUBLISHED). - AUTOMATION_STAGE_UNSPECIFIED: Automation stage is not specified. - AUTOMATION_STAGE_DRAFT: Automation is in draft stage and can be modified. - AUTOMATION_STAGE_PUBLISHED: Automation is published and immutable, ready for execution. in: query required: true schema: type: string enum: - AUTOMATION_STAGE_UNSPECIFIED - AUTOMATION_STAGE_DRAFT - AUTOMATION_STAGE_PUBLISHED default: AUTOMATION_STAGE_UNSPECIFIED - name: step description: The step's entry-point function name. in: query required: true schema: type: string - name: slot_paths description: Value-slot paths to expose as tunable params. Empty = all editable slots. in: query required: false explode: true schema: type: array items: type: string tags: - Automations "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/triggers/{trigger_id}": delete: summary: Delete Automation Trigger description: |- DeleteAutomationTrigger removes a trigger from an automation and tears down its external (BDK) trigger instance. The trigger must exist for the given stage. Returns the trigger as it existed immediately before removal. operationId: DeleteAutomationTrigger responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1DeleteAutomationTriggerResponse" 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: automation_id in: path required: true schema: type: string - name: trigger_id description: |- The external trigger ID to delete. This ID uniquely identifies the trigger in the external system. This field is populated from the URL path parameter. in: path required: true schema: type: string - name: stage description: |- The automation stage to delete the trigger from. Must be either AUTOMATION_STAGE_DRAFT or AUTOMATION_STAGE_PUBLISHED. - AUTOMATION_STAGE_UNSPECIFIED: Automation stage is not specified. - AUTOMATION_STAGE_DRAFT: Automation is in draft stage and can be modified. - AUTOMATION_STAGE_PUBLISHED: Automation is published and immutable, ready for execution. in: query required: true schema: type: string enum: - AUTOMATION_STAGE_UNSPECIFIED - AUTOMATION_STAGE_DRAFT - AUTOMATION_STAGE_PUBLISHED default: AUTOMATION_STAGE_UNSPECIFIED tags: - Automations ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/triggers/{trigger_id}:activate" : post: summary: Activate Trigger description: |- ActivateTrigger activates a trigger for an automation. The trigger must exist and be in a deactivated state. Returns the activated trigger configuration. operationId: ActivateTrigger responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ActivateTriggerResponse" 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: automation_id in: path required: true schema: type: string - name: trigger_id description: |- The external trigger ID to activate. This ID uniquely identifies the trigger in the external system. This field is populated from the URL path parameter. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/AutomationPhaseServiceActivateTriggerBody" required: true tags: - Automations ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/triggers/{trigger_id}:deactivate" : post: summary: Deactivate Trigger description: |- DeactivateTrigger deactivates a trigger for an automation. The trigger must exist and be in an activated state. Returns the deactivated trigger configuration. operationId: DeactivateTrigger responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1DeactivateTriggerResponse" 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: automation_id in: path required: true schema: type: string - name: trigger_id description: |- The external trigger ID to deactivate. This ID uniquely identifies the trigger in the external system. This field is populated from the URL path parameter. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/AutomationPhaseServiceDeactivateTriggerBody" required: true tags: - Automations "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/valueSlots": get: summary: Identify Step Value Slots description: |- IdentifyStepValueSlots returns the editable value slots of a step — the IDP prompt/options (inline literals or nested options fields) and any constants the step consumes (even when defined elsewhere in the code) — for step-level tuning. Read-only. Per AIP-136, a custom method (:identifyStepValueSlots). operationId: IdentifyStepValueSlots responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1IdentifyStepValueSlotsResponse" 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: automation_id in: path required: true schema: type: string - name: stage description: |- Which stage's code to analyze (DRAFT or PUBLISHED). - AUTOMATION_STAGE_UNSPECIFIED: Automation stage is not specified. - AUTOMATION_STAGE_DRAFT: Automation is in draft stage and can be modified. - AUTOMATION_STAGE_PUBLISHED: Automation is published and immutable, ready for execution. in: query required: true schema: type: string enum: - AUTOMATION_STAGE_UNSPECIFIED - AUTOMATION_STAGE_DRAFT - AUTOMATION_STAGE_PUBLISHED default: AUTOMATION_STAGE_UNSPECIFIED - name: step description: The step's entry-point function name (from CodeManifest.Step.entry_function.name). in: query required: true schema: type: string tags: - Automations "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:activate": post: summary: Activate Automation description: |- ActivateAutomation reactivates a previously deactivated automation. This allows the automation to execute new runs again. Returns FAILED_PRECONDITION if: - The automation has no published version - The automation is already active Per AIP-136, this is a custom method using the :activate suffix. operationId: ActivateAutomation responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ActivateAutomationResponse" 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: automation_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/AutomationServiceActivateAutomationBody" required: true tags: - Automations "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:deactivate": post: summary: Deactivate Automation description: |- DeactivateAutomation stops an automation from executing new runs. All events (scheduled, manual, webhook) will be logged but not executed. The automation can be reactivated at any time using ActivateAutomation. Returns FAILED_PRECONDITION if: - The automation has no published version - The automation is already deactivated Per AIP-136, this is a custom method using the :deactivate suffix. operationId: DeactivateAutomation responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1DeactivateAutomationResponse" 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: automation_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/AutomationServiceDeactivateAutomationBody" required: true tags: - Automations "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:duplicate": post: summary: Duplicate Automation description: |- DuplicateAutomation creates a new automation by copying an existing one within the same workspace. The duplicated automation is a new, independent entity with its own identity, ownership, and version history. Only the specified stage (draft or published) is copied, not the full version history. All phases (MAIN, POST, and PRE if they exist) are copied. Connections are copied by reference within the same workspace. If display_name is provided in the request, the duplicated automation uses that name; otherwise the server generates a default name based on the source automation's display name. Per AIP-136, this is a custom method using the :duplicate suffix. operationId: DuplicateAutomation responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1DuplicateAutomationResponse" 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: automation_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/AutomationServiceDuplicateAutomationBody" required: true tags: - Automations "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:export": post: summary: Export Automation description: |- Exports a specific revision of an automation as a ZIP bundle. Uploads the bundle to file storage and returns a 1-hour presigned download URL. The bundle contains all automation phases, connections metadata, trigger metadata, and provenance information. SPy code files are encrypted at rest within the bundle. Fails with FAILED_PRECONDITION if the encryption key is not configured. operationId: ExportAutomation responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ExportAutomationResponse" 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: automation_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/AutomationImportExportServiceExportAutomationBody" required: true tags: - Automations "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:fork": post: summary: Fork Published Automation description: |- ForkPublishedAutomation creates a draft from the last published version of an automation. This effectively resets the draft state to match the published state. Per AIP-136, this is a custom method using the :fork suffix. operationId: ForkPublishedAutomation responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ForkPublishedAutomationResponse" 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: automation_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/AutomationServiceForkPublishedAutomationBody" required: true tags: - Automations "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:move": post: summary: Move Automation description: |- Moves a specific revision of an automation directly into another workspace (in the same organization or a different one) within the same environment. Unlike export/import, this is a direct intra-platform copy and does not produce or consume a ZIP bundle. The source automation is left intact; a new draft automation is created in the target workspace. Connections and triggers are matched automatically in the target workspace. operationId: MoveAutomation responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1MoveAutomationResponse" 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: automation_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/AutomationImportExportServiceMoveAutomationBody" required: true tags: - Automations "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:publish": post: summary: Publish Automation description: |- PublishAutomation publishes an automation with the provided credentials. Creates a new immutable AutomationRevision and updates latest_published_version. Per AIP-136, this is a custom method using the :publish suffix. operationId: PublishAutomation responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1PublishAutomationResponse" 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: automation_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/AutomationServicePublishAutomationBody" required: true tags: - Automations "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:rename": post: summary: Rename Automation description: |- RenameAutomation changes the display name of an automation without modifying the automation content (code, connections, artifacts). This operation does not increment the automation version since only metadata is changed. Per AIP-136, this is a custom method using the :rename suffix. operationId: RenameAutomation responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Automation" 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: automation_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/AutomationServiceRenameAutomationBody" required: true tags: - Automations "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:restore": post: summary: Restore Automation description: |- RestoreAutomation restores an automation to a previous version. This copies the snapshot from the specified revision into the current draft, and populates restore_time, restore_version, and restore_user_id fields. Per AIP-136, this is a custom method using the :restore suffix. operationId: RestoreAutomation responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1RestoreAutomationResponse" 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: automation_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/AutomationServiceRestoreAutomationBody" required: true tags: - Automations "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:setDefaultInputs": post: summary: Set Automation Default Inputs description: |- SetAutomationDefaultInputs sets or updates default input values for an automation. Default inputs are used to pre-populate values for manual runs and fill missing inputs for trigger-based invocations. This operation updates the latest version of the specified stage in-place without creating a new version. The provided default_inputs are merged with existing defaults: - Keys present in the request overwrite existing defaults - Keys with null_value remove the default for that input - Existing keys not present in the request are preserved Per AIP-136, this is a custom method using the :setDefaultInputs suffix. operationId: SetAutomationDefaultInputs responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Automation" 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: automation_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/AutomationServiceSetAutomationDefaultInputsBody" required: true tags: - Automations "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:setLabels": post: summary: Set Automation Labels description: |- SetAutomationLabels replaces the full label set of an automation. Labels not in the given list are removed and new ones are added. An empty list removes all labels. Like RenameAutomation, this only changes metadata and does not create a new automation version. Labels are matched case-insensitively. A label already used in the workspace under a different casing is stored in that existing spelling. Per AIP-136, this is a custom method using the :setLabels suffix. operationId: SetAutomationLabels responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Automation" 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: automation_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/AutomationServiceSetAutomationLabelsBody" required: true tags: - Automations "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:setMarkedOutputs": post: summary: Set Marked Outputs description: SetMarkedOutputs sets a single marked output key for an automation. operationId: SetMarkedOutputs responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1SetMarkedOutputsResponse" 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: automation_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/AutomationPhaseServiceSetMarkedOutputsBody" required: true tags: - Automations "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:unsetMarkedOutput": post: summary: Unset Marked Output description: UnsetMarkedOutput removes a single marked output key from an automation. operationId: UnsetMarkedOutput responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1UnsetMarkedOutputResponse" 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: automation_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/AutomationPhaseServiceUnsetMarkedOutputBody" required: true tags: - Automations "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:upgradeBookConnectionVersion": post: summary: Upgrade Automation Book Connection Version description: |- UpgradeAutomationBookConnectionVersion upgrades all connections of a specific book within a draft automation to a specified target version. Every connection whose book matches will be transitioned to new_book_version in a single atomic update. The target version does not need to be the latest — any higher version is valid. This operation only works on draft automations. To upgrade connections in a published automation, first use ForkPublishedAutomation to create a draft, then call this method. Per AIP-136, this is a custom method using the :upgradeBookConnectionVersion suffix. operationId: UpgradeAutomationBookConnectionVersion responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1UpgradeAutomationBookConnectionVersionResponse" 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: automation_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/AutomationServiceUpgradeAutomationBookConnectionVersionBody" required: true tags: - Automations "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:validateImport": post: summary: Validate Automation Import description: |- Validates an automation that may have been created via import. Reports whether the automation was imported and, if so, what is still missing before it can run: connections that have no match in the workspace and trigger kinds that are not yet configured for the automation's pre-phases. Read-only; makes no changes. operationId: ValidateAutomationImport responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ValidateAutomationImportResponse" 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: automation_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/AutomationImportExportServiceValidateAutomationImportBody" required: true tags: - Automations "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:validatePublish": post: summary: Validate Automation Publish description: |- ValidateAutomationPublish checks if an automation is ready to be published. Returns information about missing credentials needed for publish. Per AIP-136, this is a custom method using the :validatePublish suffix. operationId: ValidateAutomationPublish responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ValidateAutomationPublishResponse" 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: automation_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/AutomationServiceValidateAutomationPublishBody" required: true tags: - Automations "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations:bulkUpgradeBookConnections": post: summary: Bulk Upgrade Automation Book Connections description: |- BulkUpgradeAutomationBookConnections upgrades all connections of a specific book across multiple draft automations in a single request. The book is resolved from the provided connection_id — every connection slot in each automation that belongs to that book is replaced with the new connection, regardless of alias name. Each automation is processed independently: a failure on one automation does not block the remaining automations. The automation version is incremented once per successfully upgraded automation. This operation only works on draft automations. To upgrade connections in a published automation, first use ForkPublishedAutomation to create a draft, then call this method. Per AIP-136, this is a custom method using the :bulkUpgradeBookConnections suffix. operationId: BulkUpgradeAutomationBookConnections responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1BulkUpgradeAutomationBookConnectionsResponse" 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 requestBody: content: application/json: schema: $ref: "#/components/schemas/AutomationServiceBulkUpgradeAutomationBookConnectionsBody" required: true tags: - Automations "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations:import": post: summary: Import Automation description: |- Imports an exported automation ZIP bundle into a workspace as a new draft 0.1. Connections and triggers are re-wired via caller-supplied mappings. If display_name conflicts with an existing automation in the target workspace, the name is automatically resolved by prefixing with "1 - ", "2 - ", etc. Fails with FAILED_PRECONDITION if the encryption key is not configured. Fails with INVALID_ARGUMENT if the bundle is malformed or decryption fails. operationId: ImportAutomation responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ImportAutomationResponse" 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 requestBody: content: application/json: schema: $ref: "#/components/schemas/AutomationImportExportServiceImportAutomationBody" required: true tags: - Automations "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations:listSummaries": get: summary: List Automation Summaries description: |- ListAutomationSummaries returns a paginated list of lightweight automation summaries. Unlike ListAutomations, it omits heavy fields (code, artifacts, full english_code text, etc.), making it well suited to list/grid views that only need identifying and display metadata. operationId: ListAutomationSummaries responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ListAutomationSummariesResponse" 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 summaries to return in a single response. The service may return fewer than this value. If unspecified, at most 10 summaries will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. If negative, an INVALID_ARGUMENT error will be returned. in: query required: false schema: type: integer format: int32 - name: page_token description: |- A page token received from a previous `ListAutomationSummaries` call. Provide this to retrieve the subsequent page of results. When paginating, all other parameters must match the call that provided the token. in: query required: false schema: type: string - name: show_deleted description: Filter to show/hide deleted automations. Deleted automations will be hidden by default. in: query required: false schema: type: boolean - name: filter description: |- Filter expression to restrict results. Per AIP-160, a CEL filtering expression. Supported fields for filtering: - `state`: The automation state (e.g., DRAFT, PUBLISHED) - `labels`: Automations carrying the label (case-insensitive match) Example filters: - `labels:"finance"` - `labels:"finance" OR labels:"ap"` (carries any of the labels) - `labels:"finance" AND labels:"ap"` (carries all of the labels) in: query required: false schema: type: string - name: order_by description: |- Reserved for future use. Comma-separated list of fields to order results by. Currently not implemented. Results are always ordered by `update_time desc`. in: query required: false schema: type: string tags: - Automations "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/answers": get: summary: List Run Answers description: |- Lists accepted answers submitted in the draft/test authoring experience. Answers are ordered by submission time, oldest first. operationId: ListRunAnswers responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ListRunAnswersResponse" 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: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string - name: page_size description: Maximum number to return. Defaults to 50 and is capped at 100. in: query required: false schema: type: integer format: int32 - name: page_token description: Token from the previous response for this run. in: query required: false schema: type: string tags: - Runs "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}:answer": post: summary: Answer Run description: |- Answers the current question of a draft run or an explicit test run. Published operational runs must be answered through Workbench. Repeating the same answer for the same invocation is idempotent; a conflicting answer, stale invocation, or stopped run is rejected without resuming it. operationId: AnswerRun responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Run" 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: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/RunServiceAnswerRunBody" required: true tags: - Runs "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}:replay": post: summary: Replay Run description: |- Re-executes a prior run's Main phase with updated code, returning a new run. ReplayRun only supports single-phase (Main) automations. The new run takes its code and version from the request, and inherits the rest from the source run: user_inputs, stage, and exception-handling flags. Invocation details describe the new invocation; omitted details default to TEST. Test invocations cannot replay PUBLISHED runs. previous_run is set to the source run so completed book calls can be replayed from its recordings. operationId: ReplayRun responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Run" 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: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/RunServiceReplayRunBody" required: true tags: - Runs "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs:archive": post: summary: Archive Runs description: Archives a list of runs by their unique identifiers. operationId: ArchiveRuns responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ArchiveRunsResponse" 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: automation_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/RunServiceArchiveRunsBody" required: true tags: - Runs "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/executions:run": post: summary: Run Code description: RunCode executes the provided SPy code and returns the execution status. operationId: RunCode responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1RunCodeResponse" default: description: An unexpected error response. content: application/json: schema: $ref: "#/components/schemas/rpcStatus" parameters: - name: organization_id description: The organization id for which the execution is requested in: path required: true schema: type: string - name: workspace_id description: The workspace id for which the execution is requested in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/JarvisServiceRunCodeBody" required: true tags: - Runs "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/runs/executionTimes:batchGet": get: summary: Batch Get Run Execution Times description: |- Compute the net execution time for multiple automation runs. For each run, this RPC reads all state-transition events from InfluxDB and computes: execution_duration = total_duration - exception_duration where exception_duration is the cumulative time the run spent in the AwaitingGuidance state (waiting for exception resolution) across all exception cycles. All runs must belong to the same workspace. operationId: BatchGetRunExecutionTimes responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1BatchGetRunExecutionTimesResponse" 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: names description: |- The names of the runs to compute execution time for. Format: organizations/{org}/workspaces/{workspace}/automations/{automation}/runs/{run} A maximum of 50 runs can be retrieved in a batch. All names must have the same workspace parent as the `parent` field. in: query required: true explode: true schema: type: array items: type: string tags: - Runs "/api/v1/books/{name}/{version}/test-connection": post: summary: Test Connection description: |- Tests the connectivity and authentication for a specific book. This endpoint validates that the provided authentication credentials work correctly with the specified book. It's used to verify book connectivity before attempting to invoke procedures that require authentication. operationId: TestConnection responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/bdkv1TestConnectionResponse" default: description: An unexpected error response. content: application/json: schema: $ref: "#/components/schemas/rpcStatus" parameters: - name: name description: The name of the book for which the connection will be tested in: path required: true schema: type: string - name: version description: The version of the book for which the connection will be tested in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/bdkv1Authentication" description: Authentication information required: true tags: - Books "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agent-triggers": get: summary: Retrieve Workspace Agent Trigger Instances description: Retrieve all agent trigger instances for a workspace. operationId: RetrieveWorkspaceAgentTriggerInstances responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2RetrieveWorkspaceAgentTriggerInstancesResponse" default: description: An unexpected error response. content: application/json: schema: $ref: "#/components/schemas/rpcStatus" parameters: - name: organization_id description: The id of the organization in: path required: true schema: type: string - name: workspace_id description: The id of the workspace in: path required: true schema: type: string - name: filter description: |- AIP-160 Filter expression https://google.aip.dev/160 in: query required: false schema: type: string tags: - Books ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/{book_version}/connections/with-remote-secret" : post: summary: Add Workspace Book Connection With Remote Secret description: |- Adds a book connection backed by a managed credential (referenced by id), for books whose runtime supports remote secrets. Carries no inline authentication values. operationId: AddWorkspaceBookConnectionWithRemoteSecret responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2BookConnectionResponse" default: description: An unexpected error response. content: application/json: schema: $ref: "#/components/schemas/rpcStatus" parameters: - name: organization_id description: The id of the organization in: path required: true schema: type: string - name: workspace_id description: The id of the workspace in: path required: true schema: type: string - name: book_name description: The name of the book in: path required: true schema: type: string - name: book_version description: The version of the book in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/LibraryServiceAddWorkspaceBookConnectionWithRemoteSecretBody" required: true tags: - Books ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/{book_version}/connections/{connection_id}/agent-triggers" : post: summary: Add Workspace Book Connection Agent Trigger Instance description: |- Adds a new agent trigger instance to a book connection. An agent trigger fires a single rain agent (identified by agent_id) with the configured literal prompt when the trigger condition is met. operationId: AddWorkspaceBookConnectionAgentTriggerInstance responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2AddWorkspaceBookConnectionAgentTriggerInstanceResponse" default: description: An unexpected error response. content: application/json: schema: $ref: "#/components/schemas/rpcStatus" parameters: - name: organization_id description: The id of the organization in: path required: true schema: type: string - name: workspace_id description: The id of the workspace in: path required: true schema: type: string - name: book_name description: The name of the book in: path required: true schema: type: string - name: book_version description: The version of the book in: path required: true schema: type: string - name: connection_id description: The identifier of the book connection in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/LibraryServiceAddWorkspaceBookConnectionAgentTriggerInstanceBody" required: true tags: - Books ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/{book_version}/connections/{connection_id}/copy-and-upgrade" : post: summary: Copy And Upgrade Workspace Book Connection description: |- Copy a book connection and upgrade the copy to a new version. Unlike UpgradeWorkspaceBookConnection, this endpoint does not mutate the source connection. It creates a brand-new BookConnection (with a fresh connection_id) at new_book_version, carrying over the source connection's credentials and configuration so the user does not have to re-enter them. Automations attached to the source connection are not migrated; the caller decides which automations (if any) to re-point at the new connection. new_book_version must differ from book_version. operationId: CopyAndUpgradeWorkspaceBookConnection responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2BookConnectionResponse" default: description: An unexpected error response. content: application/json: schema: $ref: "#/components/schemas/rpcStatus" parameters: - name: organization_id description: The id of the organization in: path required: true schema: type: string - name: workspace_id description: The id of the workspace in: path required: true schema: type: string - name: book_name description: The name of the book in: path required: true schema: type: string - name: book_version description: The current version of the book on the source connection in: path required: true schema: type: string - name: connection_id description: The identifier of the source book connection to copy from in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/LibraryServiceCopyAndUpgradeWorkspaceBookConnectionBody" required: true tags: - Books ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/{book_version}/connections/{connection_id}/polls" : post: summary: Add Workspace Book Connection Poll Instance description: |- Adds a poll instance for a workspace book connection. Polls are long-running background tasks that continuously monitor external systems for changes or new data. This endpoint: - Creates a new poll instance with a unique identifier - Starts the polling loop in the background - Returns the created poll instance The poll instance is scoped to a workspace book connection, which provides the authentication credentials for accessing external systems. Configuration parameters can be provided to customize polling behavior. operationId: AddWorkspaceBookConnectionPollInstance responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2AddWorkspaceBookConnectionPollInstanceResponse" default: description: An unexpected error response. content: application/json: schema: $ref: "#/components/schemas/rpcStatus" parameters: - name: organization_id description: The id of the organization in: path required: true schema: type: string - name: workspace_id description: The id of the workspace in: path required: true schema: type: string - name: book_name description: The name of the book in: path required: true schema: type: string - name: book_version description: The version of the book in: path required: true schema: type: string - name: connection_id description: The identifier of the book connection in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/LibraryServiceAddWorkspaceBookConnectionPollInstanceBody" required: true tags: - Books ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/{book_version}/connections/{connection_id}/upgrade-with-remote-secret" : put: summary: Upgrade Workspace Book Connection With Remote Secret description: |- Upgrade a connection onto a credential-capable book version, migrating its credential into the managed store. The runtime mints the managed credential from the connection's existing (legacy) secret and attaches it. operationId: UpgradeWorkspaceBookConnectionWithRemoteSecret responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2BookConnectionResponse" default: description: An unexpected error response. content: application/json: schema: $ref: "#/components/schemas/rpcStatus" parameters: - name: organization_id description: The id of the organization in: path required: true schema: type: string - name: workspace_id description: The id of the workspace in: path required: true schema: type: string - name: book_name description: The name of the book in: path required: true schema: type: string - name: book_version description: The existing version of the book in: path required: true schema: type: string - name: connection_id description: The identifier of the book connection to upgrade in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/LibraryServiceUpgradeWorkspaceBookConnectionWithRemoteSecretBody" required: true tags: - Books ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/{book_version}/connections/{connection_id}/with-remote-secret" : put: summary: Update Workspace Book Connection With Remote Secret description: |- Updates a credential-backed book connection (re-point the managed credential and/or update config/labels). Carries no inline authentication values. operationId: UpdateWorkspaceBookConnectionWithRemoteSecret responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2BookConnectionResponse" default: description: An unexpected error response. content: application/json: schema: $ref: "#/components/schemas/rpcStatus" parameters: - name: organization_id description: The id of the organization in: path required: true schema: type: string - name: workspace_id description: The id of the workspace in: path required: true schema: type: string - name: book_name description: The name of the book in: path required: true schema: type: string - name: book_version description: The version of the book in: path required: true schema: type: string - name: connection_id description: The id of the connection to update in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/LibraryServiceUpdateWorkspaceBookConnectionWithRemoteSecretBody" required: true tags: - Books "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{name}/versions": get: summary: Retrieve Workspace Book Versions description: |- Retrieves all available versions for a specific book visible in a workspace. This endpoint returns a list of all version strings available for the specified book name in the workspace context (global + workspace-private). operationId: RetrieveWorkspaceBookVersions responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2RetrieveBookVersionsResponse" default: description: An unexpected error response. content: application/json: schema: $ref: "#/components/schemas/rpcStatus" parameters: - name: organization_id description: Organization identifier in: path required: true schema: type: string - name: workspace_id description: Workspace identifier in: path required: true schema: type: string - name: name description: The name of the book to retrieve versions for in: path required: true schema: type: string tags: - Books "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{name}/{version}": get: summary: Retrieve Workspace Book description: |- Retrieves detailed information about a specific book version in a workspace. This endpoint provides comprehensive metadata about a particular book in the workspace context, including books that are private to the workspace and not visible in the global library. operationId: RetrieveWorkspaceBook responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/bdkv2RetrieveBookResponse" default: description: An unexpected error response. content: application/json: schema: $ref: "#/components/schemas/rpcStatus" parameters: - name: organization_id description: Organization identifier in: path required: true schema: type: string - name: workspace_id description: Workspace identifier in: path required: true schema: type: string - name: name description: The name of the book to be retrieved in: path required: true schema: type: string - name: version description: The version of the book to be retrieved in: path required: true schema: type: string tags: - Books "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books:latest": get: summary: Retrieve Latest Workspace Books description: |- Retrieves the latest version of every book available in the workspace. This endpoint returns metadata for the latest version of each book that is currently available in the runtime for the specified workspace. The result is the union of global library books and any workspace-private books. operationId: RetrieveLatestWorkspaceBooks responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/bdkv2RetrieveBooksResponse" default: description: An unexpected error response. content: application/json: schema: $ref: "#/components/schemas/rpcStatus" parameters: - name: organization_id description: Organization identifier in: path required: true schema: type: string - name: workspace_id description: Workspace identifier in: path required: true schema: type: string - name: page_size description: The maximum number of books to return. in: query required: false schema: type: integer format: int64 - name: page_token description: The token to use to retrieve the next page of books. in: query required: false schema: type: string - name: filter description: |- AIP-160 Filter expression https://google.aip.dev/160 in: query required: false schema: type: string tags: - Books ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/connections/{connection_id}/agent-triggers/{trigger_instance_id}" : put: summary: Update Workspace Book Connection Agent Trigger Instance description: |- Updates an existing agent trigger instance. Uses PUT semantics - all fields are required and will replace the existing values. operationId: UpdateWorkspaceBookConnectionAgentTriggerInstance responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2UpdateWorkspaceBookConnectionAgentTriggerInstanceResponse" default: description: An unexpected error response. content: application/json: schema: $ref: "#/components/schemas/rpcStatus" parameters: - name: organization_id description: The id of the organization in: path required: true schema: type: string - name: workspace_id description: The id of the workspace in: path required: true schema: type: string - name: connection_id description: The identifier of the book connection in: path required: true schema: type: string - name: trigger_instance_id description: The identifier of the agent trigger instance to update in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/LibraryServiceUpdateWorkspaceBookConnectionAgentTriggerInstanceBody" required: true tags: - Books delete: summary: Remove Workspace Book Connection Agent Trigger Instance description: Removes an agent trigger instance from a book connection. operationId: RemoveWorkspaceBookConnectionAgentTriggerInstance responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2RemoveWorkspaceBookConnectionAgentTriggerInstanceResponse" default: description: An unexpected error response. content: application/json: schema: $ref: "#/components/schemas/rpcStatus" parameters: - name: organization_id description: The id of the organization in: path required: true schema: type: string - name: workspace_id description: The id of the workspace in: path required: true schema: type: string - name: connection_id description: Book Connection ID in: path required: true schema: type: string - name: trigger_instance_id description: The identifier of the agent trigger instance to remove in: path required: true schema: type: string tags: - Books "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/connections/{connection_id}/polls/{poll_instance_id}": put: summary: Update Workspace Book Connection Poll Instance description: |- Updates an existing poll instance's name, configuration, filter expression, and poll interval. Uses PUT semantics - name and configuration replace the existing values. poll_interval_minutes is optional; when omitted, the existing interval is preserved. operationId: UpdateWorkspaceBookConnectionPollInstance responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2UpdateWorkspaceBookConnectionPollInstanceResponse" default: description: An unexpected error response. content: application/json: schema: $ref: "#/components/schemas/rpcStatus" parameters: - name: organization_id description: The id of the organization in: path required: true schema: type: string - name: workspace_id description: The id of the workspace in: path required: true schema: type: string - name: connection_id description: The identifier of the book connection in: path required: true schema: type: string - name: poll_instance_id description: The identifier of the poll instance to update in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/LibraryServiceUpdateWorkspaceBookConnectionPollInstanceBody" required: true tags: - Books delete: summary: Remove Workspace Book Connection Poll Instance description: |- Removes a running poll instance. This endpoint gracefully terminates a poll that was previously added via AddWorkspaceBookConnectionPollInstance. The poll will stop monitoring the external system and clean up any resources. operationId: RemoveWorkspaceBookConnectionPollInstance responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2RemoveWorkspaceBookConnectionPollInstanceResponse" default: description: An unexpected error response. content: application/json: schema: $ref: "#/components/schemas/rpcStatus" parameters: - name: organization_id description: The id of the organization in: path required: true schema: type: string - name: workspace_id description: The id of the workspace in: path required: true schema: type: string - name: connection_id description: Book Connection ID in: path required: true schema: type: string - name: poll_instance_id description: The identifier of the poll instance to remove in: path required: true schema: type: string tags: - Books "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/connections/{connection_id}/remote-connection": put: summary: Associate Remote Connection description: |- Associate a remote connection with a book connection. This endpoint adds a label to the book connection to associate it with a remote connection. operationId: AssociateRemoteConnection responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2BookConnectionResponse" default: description: An unexpected error response. content: application/json: schema: $ref: "#/components/schemas/rpcStatus" parameters: - name: organization_id description: The id of the organization in: path required: true schema: type: string - name: workspace_id description: The id of the workspace in: path required: true schema: type: string - name: connection_id description: The connection id of the book connection in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/LibraryServiceAssociateRemoteConnectionBody" required: true tags: - Books ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/connections/{connection_id}/remote-connection/{remote_connection_id}" : delete: summary: Disassociate Remote Connection description: |- Disassociate a remote connection from a book connection. This endpoint removes the remote connection association label from the book connection. operationId: DisassociateRemoteConnection responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2BookConnectionResponse" default: description: An unexpected error response. content: application/json: schema: $ref: "#/components/schemas/rpcStatus" parameters: - name: organization_id description: The id of the organization in: path required: true schema: type: string - name: workspace_id description: The id of the workspace in: path required: true schema: type: string - name: connection_id description: The connection id of the book connection in: path required: true schema: type: string - name: remote_connection_id description: The remote connection id to disassociate from the book connection in: path required: true schema: type: string tags: - Books "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/connections/{connection_id}:reactivate": post: summary: Reactivate Workspace Book Connection description: |- Reactivate a book connection that was scaled to zero due to inactivity. Moves the connection out of the Inactive state so the controller scales its pod back up. Internal services call this over gRPC; the HTTP route is provided so it can also be exposed to users from the UI if desired. operationId: ReactivateWorkspaceBookConnection responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2BookConnectionResponse" default: description: An unexpected error response. content: application/json: schema: $ref: "#/components/schemas/rpcStatus" parameters: - name: organization_id description: The id of the organization in: path required: true schema: type: string - name: workspace_id description: The id of the workspace in: path required: true schema: type: string - name: connection_id description: The identifier of the book connection to reactivate in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/LibraryServiceReactivateWorkspaceBookConnectionBody" required: true tags: - Books "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/connections:batchGet": post: summary: Retrieve Workspace Book Connections By Ids description: |- Retrieve multiple book connections by id in one call. This endpoint is designed to avoid LISTing all connections in a workspace when the caller already knows the specific connection IDs it needs. operationId: RetrieveWorkspaceBookConnectionsByIds responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2RetrieveBooksConnectionsResponse" default: description: An unexpected error response. content: application/json: schema: $ref: "#/components/schemas/rpcStatus" parameters: - name: organization_id description: The id of the organization in: path required: true schema: type: string - name: workspace_id description: The id of the workspace in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/LibraryServiceRetrieveWorkspaceBookConnectionsByIdsBody" required: true tags: - Books "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/polls": get: summary: Retrieve Workspace Poll Instances description: Retrieve all poll instances for a workspace operationId: RetrieveWorkspacePollInstances responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2RetrieveWorkspacePollInstancesResponse" default: description: An unexpected error response. content: application/json: schema: $ref: "#/components/schemas/rpcStatus" parameters: - name: organization_id description: The id of the organization in: path required: true schema: type: string - name: workspace_id description: The id of the workspace in: path required: true schema: type: string - name: filter description: |- AIP-160 Filter expression https://google.aip.dev/160 in: query required: false schema: type: string tags: - Books "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/polls/{poll_instance_id}/automations": put: summary: Set Automations For Poll Instance description: |- Attach automations to a poll instance. The caller sends the full desired list; the existing list is replaced. operationId: SetAutomationsForPollInstance responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v2SetAutomationsForPollInstanceResponse" default: description: An unexpected error response. content: application/json: schema: $ref: "#/components/schemas/rpcStatus" parameters: - name: organization_id description: The id of the organization in: path required: true schema: type: string - name: workspace_id description: The id of the workspace in: path required: true schema: type: string - name: poll_instance_id description: The identifier of the poll instance in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/LibraryServiceSetAutomationsForPollInstanceBody" required: true tags: - Books "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/tags": get: summary: Retrieve Workspace Tags description: |- Retrieves all available tags from books visible in a workspace. This endpoint returns a consolidated list of all tags used across the books visible in the workspace context (global library + workspace-private books). operationId: RetrieveWorkspaceTags responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/bdkv2RetrieveTagsResponse" default: description: An unexpected error response. content: application/json: schema: $ref: "#/components/schemas/rpcStatus" parameters: - name: organization_id description: Organization identifier in: path required: true schema: type: string - name: workspace_id description: Workspace identifier in: path required: true schema: type: string tags: - Books "/api/v1/organizations/{organization_id}/files/{file}": delete: summary: Delete File description: Delete file operationId: DeleteOrganizationFile responses: "200": description: A successful response. content: application/json: schema: type: object properties: {} 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: file in: path required: true schema: type: string tags: - Files "/api/v1/organizations/{organization_id}/files/{file}/metadata": get: summary: Get File Metadata description: Get file metadata only operationId: GetOrganizationFileMetadata responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1FileMetadata" 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: file in: path required: true schema: type: string tags: - Files "/api/v1/organizations/{organization_id}/files/{file}:download": get: summary: Download File description: |- Download file content Direct REST Implementation: - Binary response with metadata in HTTP headers operationId: DownloadOrganizationFile responses: "200": description: File content headers: Content-Disposition: description: Attachment with filename schema: type: string Content-Length: description: File size in bytes schema: type: string Content-Type: description: MIME type of the file schema: type: string content: application/octet-stream: schema: type: string format: binary default: description: An unexpected error response. content: application/octet-stream: schema: $ref: "#/components/schemas/rpcStatus" parameters: - name: organization_id in: path required: true schema: type: string - name: file in: path required: true schema: type: string tags: - Files "/api/v1/organizations/{organization_id}/files/{file}:generateDownloadUrl": post: summary: Generate Download Url description: Generate presigned URL for direct download operationId: GenerateOrganizationDownloadUrl responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1GenerateDownloadUrlResponse" 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: file in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/FilesServiceGenerateDownloadUrlBody" required: true tags: - Files "/api/v1/organizations/{organization_id}/files:generateUploadUrl": post: summary: Generate Upload Url description: Generate presigned URL for direct upload operationId: GenerateOrganizationUploadUrl responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1GenerateUploadUrlResponse" 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/FilesServiceGenerateUploadUrlBody" required: true tags: - Files "/api/v1/organizations/{organization_id}/files:upload": post: summary: Upload File description: |- Upload file content Direct REST Implementation: - multipart/form-data with filename and file fields - Returns complete FileMetadata with server-generated fields The lifetime of the file is the lifetime of the organization, ie, if the organization is deleted, its file will also be deleted. operationId: UploadOrganizationFile responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1UploadFileResponse" "201": description: File uploaded successfully headers: Location: description: URL of the created file resource schema: type: string content: application/json: schema: {} 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: multipart/form-data: schema: $ref: "#/components/schemas/apiHttpBody" description: Raw HTTP body containing multipart/form-data required: true tags: - Files "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/files/{file}:paginateValueContent": get: summary: Paginate Value Content description: Paginate content from an offloaded value file. operationId: PaginateValueContent responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1PaginateValueContentResponse" 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: file in: path required: true schema: type: string - name: value_kind description: |- Value type used to deserialize payload bytes. - VALUE_KIND_UNSPECIFIED: Default unspecified value kind. - VALUE_KIND_TEXT: UTF-8 text payload. - VALUE_KIND_LIST: Serialized list payload. - VALUE_KIND_DICTIONARY: Serialized dictionary payload. - VALUE_KIND_TABLE: Arrow table payload. - VALUE_KIND_SET: Offloaded set of hashable values. in: query required: true schema: type: string enum: - VALUE_KIND_UNSPECIFIED - VALUE_KIND_TEXT - VALUE_KIND_LIST - VALUE_KIND_DICTIONARY - VALUE_KIND_TABLE - VALUE_KIND_SET default: VALUE_KIND_UNSPECIFIED - name: page_size description: Maximum number of elements/rows/chars to return in this page. in: query required: false schema: type: integer format: int32 - name: page_token description: Opaque token for fetching the next page. in: query required: false schema: type: string tags: - Files "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/files/{file}:replaceContent": post: summary: Replace File Content description: |- Replace an existing file's content, preserving its identity. The resource name and create_time are unchanged, so existing references to the file stay valid. Direct REST Implementation: - multipart/form-data with a single content field - Returns the updated FileMetadata operationId: ReplaceFileContent responses: "200": description: File content replaced successfully content: application/json: schema: $ref: "#/components/schemas/v1ReplaceFileContentResponse" 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: file in: path required: true schema: type: string requestBody: content: multipart/form-data: schema: $ref: "#/components/schemas/apiHttpBody" description: |- Raw HTTP body containing multipart/form-data with a single `content` field. The file keeps its original filename. required: true tags: - Files ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/guideEntries/{guide_entry_id}/applications" : get: summary: List Guide Applications description: |- Lists applications of a guide entry. Returns a list of applications showing when and where the guide was applied. UI can use this to fetch run details from Jeeves for the Applied Runs table. operationId: ListGuideApplications responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ListGuideApplicationsResponse" 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: automation_id in: path required: true schema: type: string - name: guide_entry_id in: path required: true schema: type: string - name: page_size description: |- The maximum number of applications to return. The service may return fewer than this value. If unspecified, at most 50 applications will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. Note: These limits are enforced by server-side validation. in: query required: false schema: type: integer format: int32 - name: page_token description: |- The page token, received from a previous `ListGuideApplications` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `ListGuideApplications` must match the call that provided the page token. in: query required: false schema: type: string tags: - Exceptions ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/guideEntries/{guide_entry_id}:listVersions" : get: summary: List Guide Entry Versions description: |- Lists all versions of a guide entry, newest first (by DESC version order). Unlike GetGuideEntry/ListGuideEntries (which return only the effective version per entry), this returns the full version history for a single guide entry so clients can inspect and revert to a previous version. operationId: ListGuideEntryVersions responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ListGuideEntryVersionsResponse" 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: automation_id in: path required: true schema: type: string - name: guide_entry_id in: path required: true schema: type: string - name: page_size description: |- The maximum number of versions to return. The service may return fewer. If unspecified, at most 50 versions 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: |- The page token, received from a previous `ListGuideEntryVersions` call. Provide this to retrieve the subsequent page. in: query required: false schema: type: string tags: - Exceptions ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/guideEntries/{guide_entry_id}:revert" : post: summary: Revert Guide Entry description: |- Reverts a guide entry to a previous version. Forward-only (like grimoire's RestoreAutomation): copies the target version's content into a NEW version row with a bumped minor version and state = PENDING_APPROVAL. No rows are removed and no pointer is moved backward. Like an ordinary update, the new version becomes the latest version but must be approved before the agent auto-applies it. The new version records which version it was reverted from. operationId: RevertGuideEntry responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1GuideEntry" 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: automation_id in: path required: true schema: type: string - name: guide_entry_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/TroubleshootingGuideServiceRevertGuideEntryBody" required: true tags: - Exceptions ? "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/guideEntries/{guide_entry_id}:transitionState" : post: summary: Transition Guide Entry State description: |- Transitions a guide entry to a new state. - PENDING_APPROVAL -> APPROVED: Approve the guide entry for use by the agent - PENDING_APPROVAL -> REJECTED: Reject the guide entry - Any state -> ARCHIVED: Archive the guide entry (soft deletes and updates the delete time) operationId: TransitionGuideEntryState responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1GuideEntry" 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: automation_id in: path required: true schema: type: string - name: guide_entry_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/TroubleshootingGuideServiceTransitionGuideEntryStateBody" required: true tags: - Exceptions "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/guideEntries:queryStats": post: summary: Query Guide Stats description: |- Queries usage statistics for guide entries. Returns aggregated statistics including total occurrences and filtered occurrences within an optional date range. This is a custom method for analytics/reporting, not a standard List operation. operationId: QueryGuideStats responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1QueryGuideStatsResponse" 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: automation_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/TroubleshootingGuideServiceQueryGuideStatsBody" required: true tags: - Exceptions "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}:runAssistant": post: summary: Create Run Assistant description: |- Creates an interactive AI assistant (a Rain thread) for a run, pre-staged with the automation's code and connections. Returns the rain_thread_id. Despite the "Create" prefix this is a custom action, not an AIP-133 standard Create: it has no resource body (the only input is the parent run, bound from the path) and returns a thread id rather than a resource. operationId: CreateRunAssistant responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1CreateRunAssistantResponse" 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: automation_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string tags: - Exceptions "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/exceptionClusters": get: summary: List Exception Clusters description: |- Lists exception clusters -- one row per distinct symptom, aggregated server-side so a client never has to hold every exception to group them. A cluster is (automation, automation_version, cluster label): a fix ships as a new version, so the same symptom on two versions is two problems. Clusters are derived from Exception.cluster rather than stored, so they are not yet resources; ExceptionGroup sets the same precedent. operationId: ListExceptionClusters responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ListExceptionClustersResponse" 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: filter description: |- Optional filter applied to exceptions BEFORE aggregation (same syntax as ListExceptions). Every count and timestamp on the returned clusters respects it. Example: a queue lane that keeps recently-settled runs visible sends 'state = "PENDING" OR (state = "RESOLVED" AND update_time > "...")'. in: query required: false schema: type: string - name: page_size description: |- The maximum number of clusters to return. If unspecified, at most 50 clusters 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: The page token from a previous ListExceptionClusters call. in: query required: false schema: type: string - name: order_by description: |- How to rank the clusters. Defaults to CLUSTER_ORDER_URGENCY. - CLUSTER_ORDER_UNSPECIFIED: Defaults to CLUSTER_ORDER_URGENCY. - CLUSTER_ORDER_URGENCY: Biggest class first: most members, oldest first among equals. For work still held, where one conversation buys the most. - CLUSTER_ORDER_AGE: Longest-waiting run first, whatever size class it sits in. The counterpart to urgency, not a variation on it: a single run stuck since this morning outranks a class of six that started ten minutes ago. - CLUSTER_ORDER_RECENCY: Most recent activity first. For work already settled, where size means nothing and the only useful question is what happened last. in: query required: false schema: type: string enum: - CLUSTER_ORDER_UNSPECIFIED - CLUSTER_ORDER_URGENCY - CLUSTER_ORDER_AGE - CLUSTER_ORDER_RECENCY default: CLUSTER_ORDER_UNSPECIFIED tags: - Exceptions "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/exceptionGroups:setRouting": post: summary: Set Exception Group Routing description: |- Sets default assignees for exception groups in a workspace. Sets or clears the default assignee for one or more exception groups. When a default assignee is set for a group, new exceptions in that group will be automatically assigned to that user at creation time. Set default_assignee to "" to clear the default (no auto-assignment). operationId: SetExceptionGroupRouting responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1SetExceptionGroupRoutingResponse" 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 requestBody: content: application/json: schema: $ref: "#/components/schemas/ExceptionManagerServiceSetExceptionGroupRoutingBody" required: true tags: - Exceptions "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/exceptions/{exception_id}:hermesContext": get: summary: Get Hermes Exception Context description: |- Returns the opening `` payload for the Hermes agent. Hermes has no tool for reading the exception it was raised on, so this payload IS its knowledge of what failed: the interpreter message, the failing location, the variables the failing statement read and the values they held, the run's inputs, and a window of the source around the line that raised. The caller opens the Rain thread itself and sends this as (or ahead of) the operator's first message. Read-only and idempotent, so a caller that lost the payload -- a page reload, a second browser tab -- asks again rather than reconstructing it. That is the point: the payload lives here, not in whatever opened the thread. operationId: GetHermesExceptionContext responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1GetHermesExceptionContextResponse" 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: exception_id in: path required: true schema: type: string tags: - Exceptions "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/exceptions:archive": post: summary: Archive Exceptions description: |- Archives PENDING exceptions matching a filter. Transitions exceptions from PENDING to ARCHIVED state. RESOLVED exceptions are ignored (already complete, no need to archive). Use this when giving up on unresolved exceptions. operationId: ArchiveExceptions responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ArchiveExceptionsResponse" 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 requestBody: content: application/json: schema: $ref: "#/components/schemas/ExceptionManagerServiceArchiveExceptionsBody" required: true tags: - Exceptions "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/exceptions:assign": post: summary: Assign Exceptions description: |- Assigns exceptions to a user. Supports three assignment scopes: 1. Single exception: set `name` to target one exception. 2. Group + automation: set `filter` with group and automation to target exceptions for a specific group within a specific automation. 3. Group + workspace: set `filter` with group only to target all exceptions for a group across the entire workspace. Set `assignee` to "" to clear the assignment. operationId: AssignExceptions responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1AssignExceptionsResponse" 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 requestBody: content: application/json: schema: $ref: "#/components/schemas/ExceptionManagerServiceAssignExceptionsBody" required: true tags: - Exceptions "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/exceptions:countByAssignee": get: summary: Count Exceptions By Assignee description: |- Counts exceptions by assignee. Returns a list of assignees with their exception counts. Useful for workload distribution dashboards and identifying unassigned exceptions. operationId: CountExceptionsByAssignee responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1CountExceptionsByAssigneeResponse" 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: filter description: |- Optional filter to apply before counting (same syntax as ListExceptions). Use this to count within a specific state, group, time range, etc. Example: "state = PENDING" to count only pending exceptions by assignee. Example: "group = \"missing_values\"" to count exceptions in missing_values group by assignee. in: query required: false schema: type: string - name: page_size description: |- The maximum number of assignees to return. If unspecified, at most 50 assignees 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: The page token from a previous CountExceptionsByAssignee call. in: query required: false schema: type: string tags: - Exceptions "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/exceptions:queryInsights": post: summary: Query Exception Insights description: |- Queries exception insights including MTTR and trends over time periods. Useful for dashboards and analytics to understand exception patterns and resolution times. This is a custom method for analytics/reporting, not a standard Get operation. operationId: QueryExceptionInsights responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1QueryExceptionInsightsResponse" 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 requestBody: content: application/json: schema: $ref: "#/components/schemas/ExceptionManagerServiceQueryExceptionInsightsBody" required: true tags: - Exceptions "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/exceptions:retry": post: summary: Retry Exceptions description: |- Retries multiple exceptions in a single request. Only PENDING exceptions are retried; RESOLVED and ARCHIVED exceptions are skipped. operationId: RetryExceptions responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1RetryExceptionsResponse" 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 requestBody: content: application/json: schema: $ref: "#/components/schemas/ExceptionManagerServiceRetryExceptionsBody" required: true tags: - Exceptions "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/exceptions:skip": post: summary: Skip Exceptions description: |- Skips multiple exceptions in a single request. Only PENDING exceptions are skipped; RESOLVED and ARCHIVED exceptions are ignored. operationId: SkipExceptions responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1SkipExceptionsResponse" 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 requestBody: content: application/json: schema: $ref: "#/components/schemas/ExceptionManagerServiceSkipExceptionsBody" required: true tags: - Exceptions "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/exceptions:unarchive": post: summary: Unarchive Exceptions description: |- Unarchives ARCHIVED exceptions back to PENDING state. Use this to undo accidental archive operations. Non-ARCHIVED exceptions are ignored. operationId: UnarchiveExceptions responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1UnarchiveExceptionsResponse" 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 requestBody: content: application/json: schema: $ref: "#/components/schemas/ExceptionManagerServiceUnarchiveExceptionsBody" required: true tags: - Exceptions "/api/v1/backendTypes": get: summary: List Backend Types description: |- Catalog of supported backend types and their configuration shape. UIs render configuration forms from this; new backend types appear here automatically when added on the server. operationId: ListBackendTypes responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ListBackendTypesResponse" default: description: An unexpected error response. content: application/json: schema: $ref: "#/components/schemas/rpcStatus" tags: - Secrets "/api/v1/organizations/{organization_id}/backends": get: summary: List Backends description: List Backends. operationId: ListBackends responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ListBackendsResponse" 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 in: query required: false schema: type: integer format: int32 - name: page_token in: query required: false schema: type: string - name: filter description: AIP-160 filter expression. See https://google.aip.dev/160. in: query required: false schema: type: string tags: - Secrets post: summary: Create Backend description: Create Backend. operationId: CreateBackend responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Backend" 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/v1Backend" description: |- The backend body. `backend.display_name` is required. `backend.name`, `backend.create_time`, `backend.etag`, `backend.status`, and `backend.kognitos_managed` are set by the server and ignored on input. The id (trailing segment of `backend.name`) is generated by the server as `-` (e.g. `aws-7az92kdr`). required: true tags: - Secrets "/api/v1/organizations/{organization_id}/backends/{backend_id}": get: summary: Get Backend description: Get Backend. operationId: GetBackend responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Backend" 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: backend_id in: path required: true schema: type: string tags: - Secrets patch: summary: Update Backend description: Update Backend. operationId: UpdateBackend responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Backend" 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: backend_id in: path required: true schema: type: string requestBody: content: application/json: schema: type: object properties: type_id: type: string description: |- Stable identifier matching a BackendTypeInfo.type_id returned by ListBackendTypes. e.g. "aws-secrets-manager" for BYO, "kognitos-managed" for the platform default (opaque — implementation hidden from callers). config: type: object description: |- Backend-specific configuration. Schema lives in the catalog (`BackendTypeInfo.config_fields`); server validates at write time. auth: $ref: "#/components/schemas/v1AuthConfig" status: $ref: "#/components/schemas/v1BackendStatus" create_time: type: string format: date-time etag: type: string kognitos_managed: type: boolean description: |- True when this backend is the Kognitos-managed platform default — its implementation, config, and credentials are entirely opaque to the customer and only Kognitos can change it. False for customer- owned backends (BYO), which the customer creates, configures, and can update or delete. display_name: type: string description: |- Human-readable label, customer-chosen at create time. Mutable via UpdateBackend without changing the resource name. Required on `CreateBackend` (server rejects empty); on read-back, falls back to the trailing-segment id for backends predating this field. required: true tags: - Secrets delete: summary: Delete Backend description: Delete Backend. operationId: DeleteBackend responses: "200": description: A successful response. content: application/json: schema: type: object properties: {} 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: backend_id in: path required: true schema: type: string tags: - Secrets "/api/v1/organizations/{organization_id}/oauthApps": get: summary: List O Auth Apps description: List O Auth Apps. operationId: ListOAuthApps responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ListOAuthAppsResponse" 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: query required: false schema: type: string - name: page_size in: query required: false schema: type: integer format: int32 - name: page_token in: query required: false schema: type: string - name: filter description: AIP-160 filter expression. See https://google.aip.dev/160. in: query required: false schema: type: string tags: - Secrets post: summary: Create O Auth App description: Create O Auth App. operationId: CreateOAuthApp responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1OAuthApp" default: description: An unexpected error response. content: application/json: schema: $ref: "#/components/schemas/rpcStatus" parameters: - name: organization_id description: Empty organization_id creates in the shared tier. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/OAuthAppServiceCreateOAuthAppBody" required: true tags: - Secrets "/api/v1/organizations/{organization_id}/oauthApps/{oauth_app_id}": get: summary: Get O Auth App description: Get O Auth App. operationId: GetOAuthApp responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1OAuthApp" 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: oauth_app_id in: path required: true schema: type: string - name: workspace_id in: query required: false schema: type: string tags: - Secrets patch: summary: Update O Auth App description: Update O Auth App. operationId: UpdateOAuthApp responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1OAuthApp" 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: oauth_app_id in: path required: true schema: type: string - name: workspace_id in: query required: false schema: type: string - name: update_mask description: |- Updatable: `display_name`, `metadata`, `secret_type`. `secret_type` is set-once: resending the current value is a no-op, a different one is rejected. Empty ⇒ every populated updatable field (AIP-134), so clearing `metadata` requires naming it here. in: query required: false schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/v1OAuthApp" description: "`oauth_app.etag`, when set, must match the app's current etag (AIP-154)." required: true tags: - Secrets delete: summary: Delete O Auth App description: Delete O Auth App. operationId: DeleteOAuthApp responses: "200": description: A successful response. content: application/json: schema: type: object properties: {} 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: oauth_app_id in: path required: true schema: type: string - name: workspace_id in: query required: false schema: type: string - name: purge_credentials description: |- When true, also delete the stored client credentials from the managed credential store. Default leaves them (mirrors `--purge-credentials` on backends); purge errors are logged, not fatal. in: query required: false schema: type: boolean tags: - Secrets "/api/v1/organizations/{organization_id}/secrets": get: summary: List Secrets description: List Secrets. operationId: ListSecrets responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ListSecretsResponse" 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: query required: false schema: type: string - name: page_size in: query required: false schema: type: integer format: int32 - name: page_token in: query required: false schema: type: string - name: filter description: AIP-160 filter expression. See https://google.aip.dev/160. in: query required: false schema: type: string tags: - Secrets post: summary: Create Secret description: Create Secret. operationId: CreateSecret responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Secret" default: description: An unexpected error response. content: application/json: schema: $ref: "#/components/schemas/rpcStatus" parameters: - name: organization_id description: Empty organization_id creates in the shared tier. in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/SecretServiceCreateSecretBody" required: true tags: - Secrets "/api/v1/organizations/{organization_id}/secrets/{secret_id}": get: summary: Get Secret description: Get Secret. operationId: GetSecret responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Secret" 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: secret_id in: path required: true schema: type: string - name: workspace_id in: query required: false schema: type: string tags: - Secrets patch: summary: Update Secret description: Update Secret. operationId: UpdateSecret responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Secret" 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: secret_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/SecretServiceUpdateSecretBody" required: true tags: - Secrets delete: summary: Delete Secret description: Delete Secret. operationId: DeleteSecret responses: "200": description: A successful response. content: application/json: schema: type: object properties: {} 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: secret_id in: path required: true schema: type: string - name: workspace_id in: query required: false schema: type: string - name: purge_backend description: |- When true, delete the underlying backend storage for every version, including any versions that were adopted (not created by Gringotts). Default (false) only removes the Gringotts wrapper — adopted backend data stays put. in: query required: false schema: type: boolean tags: - Secrets "/api/v1/organizations/{organization_id}/secrets/{secret_id}:addVersion": post: summary: Add Secret Version description: Add Secret Version. operationId: AddSecretVersion responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1AddSecretVersionResponse" 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: secret_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/SecretServiceAddSecretVersionBody" required: true tags: - Secrets "/api/v1/organizations/{organization_id}/secrets:adopt": post: summary: Adopt Secret description: |- Wrap an existing backend entry as a GringottsSecret. No payload is written; version 1 of the new secret references the existing storage. operationId: AdoptSecret responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Secret" 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/SecretServiceAdoptSecretBody" required: true tags: - Secrets "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/backends": get: summary: List Backends description: List Backends. operationId: ListWorkspaceBackends responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ListBackendsResponse" 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 in: query required: false schema: type: integer format: int32 - name: page_token in: query required: false schema: type: string - name: filter description: AIP-160 filter expression. See https://google.aip.dev/160. in: query required: false schema: type: string tags: - Secrets post: summary: Create Backend description: Create Backend. operationId: CreateWorkspaceBackend responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Backend" 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 requestBody: content: application/json: schema: $ref: "#/components/schemas/v1Backend" description: |- The backend body. `backend.display_name` is required. `backend.name`, `backend.create_time`, `backend.etag`, `backend.status`, and `backend.kognitos_managed` are set by the server and ignored on input. The id (trailing segment of `backend.name`) is generated by the server as `-` (e.g. `aws-7az92kdr`). required: true tags: - Secrets "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/backends/{backend_id}": get: summary: Get Backend description: Get Backend. operationId: GetWorkspaceBackend responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Backend" 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: backend_id in: path required: true schema: type: string tags: - Secrets patch: summary: Update Backend description: Update Backend. operationId: UpdateWorkspaceBackend responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Backend" 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: backend_id in: path required: true schema: type: string requestBody: content: application/json: schema: type: object properties: type_id: type: string description: |- Stable identifier matching a BackendTypeInfo.type_id returned by ListBackendTypes. e.g. "aws-secrets-manager" for BYO, "kognitos-managed" for the platform default (opaque — implementation hidden from callers). config: type: object description: |- Backend-specific configuration. Schema lives in the catalog (`BackendTypeInfo.config_fields`); server validates at write time. auth: $ref: "#/components/schemas/v1AuthConfig" status: $ref: "#/components/schemas/v1BackendStatus" create_time: type: string format: date-time etag: type: string kognitos_managed: type: boolean description: |- True when this backend is the Kognitos-managed platform default — its implementation, config, and credentials are entirely opaque to the customer and only Kognitos can change it. False for customer- owned backends (BYO), which the customer creates, configures, and can update or delete. display_name: type: string description: |- Human-readable label, customer-chosen at create time. Mutable via UpdateBackend without changing the resource name. Required on `CreateBackend` (server rejects empty); on read-back, falls back to the trailing-segment id for backends predating this field. required: true tags: - Secrets delete: summary: Delete Backend description: Delete Backend. operationId: DeleteWorkspaceBackend responses: "200": description: A successful response. content: application/json: schema: type: object properties: {} 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: backend_id in: path required: true schema: type: string tags: - Secrets "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/oauthApps": get: summary: List O Auth Apps description: List O Auth Apps. operationId: ListWorkspaceOAuthApps responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ListOAuthAppsResponse" 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 in: query required: false schema: type: integer format: int32 - name: page_token in: query required: false schema: type: string - name: filter description: AIP-160 filter expression. See https://google.aip.dev/160. in: query required: false schema: type: string tags: - Secrets post: summary: Create O Auth App description: Create O Auth App. operationId: CreateWorkspaceOAuthApp responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1OAuthApp" default: description: An unexpected error response. content: application/json: schema: $ref: "#/components/schemas/rpcStatus" parameters: - name: organization_id description: Empty organization_id creates in the shared tier. in: path required: true schema: type: string - name: workspace_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/OAuthAppServiceCreateOAuthAppBody" required: true tags: - Secrets "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/oauthApps/{oauth_app_id}": get: summary: Get O Auth App description: Get O Auth App. operationId: GetWorkspaceOAuthApp responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1OAuthApp" 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: oauth_app_id in: path required: true schema: type: string tags: - Secrets patch: summary: Update O Auth App description: Update O Auth App. operationId: UpdateWorkspaceOAuthApp responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1OAuthApp" 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: oauth_app_id in: path required: true schema: type: string - name: update_mask description: |- Updatable: `display_name`, `metadata`, `secret_type`. `secret_type` is set-once: resending the current value is a no-op, a different one is rejected. Empty ⇒ every populated updatable field (AIP-134), so clearing `metadata` requires naming it here. in: query required: false schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/v1OAuthApp" description: "`oauth_app.etag`, when set, must match the app's current etag (AIP-154)." required: true tags: - Secrets delete: summary: Delete O Auth App description: Delete O Auth App. operationId: DeleteWorkspaceOAuthApp responses: "200": description: A successful response. content: application/json: schema: type: object properties: {} 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: oauth_app_id in: path required: true schema: type: string - name: purge_credentials description: |- When true, also delete the stored client credentials from the managed credential store. Default leaves them (mirrors `--purge-credentials` on backends); purge errors are logged, not fatal. in: query required: false schema: type: boolean tags: - Secrets "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/secrets": get: summary: List Secrets description: List Secrets. operationId: ListWorkspaceSecrets responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ListSecretsResponse" 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 in: query required: false schema: type: integer format: int32 - name: page_token in: query required: false schema: type: string - name: filter description: AIP-160 filter expression. See https://google.aip.dev/160. in: query required: false schema: type: string tags: - Secrets post: summary: Create Secret description: Create Secret. operationId: CreateWorkspaceSecret responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Secret" default: description: An unexpected error response. content: application/json: schema: $ref: "#/components/schemas/rpcStatus" parameters: - name: organization_id description: Empty organization_id creates in the shared tier. in: path required: true schema: type: string - name: workspace_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/SecretServiceCreateSecretBody" required: true tags: - Secrets "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/secrets/{secret_id}": get: summary: Get Secret description: Get Secret. operationId: GetWorkspaceSecret responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Secret" 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: secret_id in: path required: true schema: type: string tags: - Secrets patch: summary: Update Secret description: Update Secret. operationId: UpdateWorkspaceSecret responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Secret" 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: secret_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/SecretServiceUpdateSecretBody" required: true tags: - Secrets delete: summary: Delete Secret description: Delete Secret. operationId: DeleteWorkspaceSecret responses: "200": description: A successful response. content: application/json: schema: type: object properties: {} 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: secret_id in: path required: true schema: type: string - name: purge_backend description: |- When true, delete the underlying backend storage for every version, including any versions that were adopted (not created by Gringotts). Default (false) only removes the Gringotts wrapper — adopted backend data stays put. in: query required: false schema: type: boolean tags: - Secrets "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/secrets/{secret_id}:addVersion": post: summary: Add Secret Version description: Add Secret Version. operationId: AddWorkspaceSecretVersion responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1AddSecretVersionResponse" 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: secret_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/SecretServiceAddSecretVersionBody" required: true tags: - Secrets "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/secrets:adopt": post: summary: Adopt Secret description: |- Wrap an existing backend entry as a GringottsSecret. No payload is written; version 1 of the new secret references the existing storage. operationId: AdoptWorkspaceSecret responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Secret" 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 requestBody: content: application/json: schema: $ref: "#/components/schemas/SecretServiceAdoptSecretBody" required: true tags: - Secrets "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}:discoverInventory": get: summary: Discover Inventory description: |- Enumerate raw entries in the backend that serves a given scope, whether or not Gringotts created them. Used by clients to power a "pick existing entry" UI on the create-secret flow. operationId: DiscoverInventory responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1DiscoverInventoryResponse" 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: backend_id description: |- Backend to inspect. Required when the scope has multiple applicable backends; optional when there's exactly one (server picks). in: query required: false schema: type: string - name: page_size in: query required: false schema: type: integer format: int32 - name: page_token in: query required: false schema: type: string - name: filter description: AIP-160 filter expression. See https://google.aip.dev/160. in: query required: false schema: type: string tags: - Secrets "/api/v1/organizations/{organization_id}:discoverInventory": get: summary: Discover Inventory description: |- Enumerate raw entries in the backend that serves a given scope, whether or not Gringotts created them. Used by clients to power a "pick existing entry" UI on the create-secret flow. operationId: DiscoverOrganizationInventory responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1DiscoverInventoryResponse" 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: query required: false schema: type: string - name: backend_id description: |- Backend to inspect. Required when the scope has multiple applicable backends; optional when there's exactly one (server picks). in: query required: false schema: type: string - name: page_size in: query required: false schema: type: integer format: int32 - name: page_token in: query required: false schema: type: string - name: filter description: AIP-160 filter expression. See https://google.aip.dev/160. in: query required: false schema: type: string tags: - Secrets "/api/v1/secretTypes": get: summary: List Secret Types description: List Secret Types. operationId: ListSecretTypes responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ListSecretTypesResponse" default: description: An unexpected error response. content: application/json: schema: $ref: "#/components/schemas/rpcStatus" parameters: - name: page_size in: query required: false schema: type: integer format: int32 - name: page_token in: query required: false schema: type: string - name: filter description: AIP-160 filter expression. See https://google.aip.dev/160. in: query required: false schema: type: string tags: - Secrets "/api/v1/secretTypes/{secret_type_id}": get: summary: Get Secret Type description: Get Secret Type. operationId: GetSecretType responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1SecretType" default: description: An unexpected error response. content: application/json: schema: $ref: "#/components/schemas/rpcStatus" parameters: - name: secret_type_id in: path required: true schema: type: string tags: - Secrets "/api/v1/secretTypes:validateSchema": post: summary: Validate Secret Schema description: |- Validate a typed payload against a schema. Pure check — no stored secret is read, no payload is persisted. Returns `valid = false` plus per-field violations on mismatch; never an `INVALID_ARGUMENT` status. operationId: ValidateSecretSchema responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ValidateSecretSchemaResponse" default: description: An unexpected error response. content: application/json: schema: $ref: "#/components/schemas/rpcStatus" requestBody: content: application/json: schema: $ref: "#/components/schemas/v1ValidateSecretSchemaRequest" required: true tags: - Secrets "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/assets": get: summary: List Assets description: List assets in a workspace, optionally filtered by folder. operationId: ListAssets responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ListAssetsResponse" 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: folder_name description: |- If set, list only assets in this folder. If empty, list assets at the workspace root (no folder). Use the special value "*" to list all assets across all folders. in: query required: false schema: type: string - name: page_size description: "Maximum number of assets to return. Valid: 1–1000. Default: 50." in: query required: false schema: type: integer format: int32 - name: page_token description: Page token from a previous ListAssets call. in: query required: false schema: type: string - name: filter description: |- AIP-160 filter expression. Filterable fields: display_name — string equality or substring: display_name = "report" or display_name : "rep" mime_type — string equality or substring: mime_type = "application/pdf" or mime_type : "pdf" created_by — exact string equality: created_by = "user@example.com" tags — has-tag check (: operator): tags : "quarterly" tags = "quarterly" is also accepted and behaves identically. Matching is case-insensitive: tags : "QUARTERLY" matches "Quarterly". Each term checks one tag; combine several with AND / OR. reference_uri — exact string equality: reference_uri = "bishop://{id}--{filename}" Useful when Jarvis or another caller already holds a bishop:// handle and needs to resolve it back to the full Asset resource. A bare resource name or presigned HTTPS URL is also accepted; any org/workspace such a value carries is ignored — org/workspace are always taken from `parent` above. Logical operators AND, OR, and parentheses are supported. Examples: filter = "mime_type = \"application/pdf\"" filter = "tags : \"quarterly\" AND created_by = \"alice@example.com\"" filter = "(mime_type : \"image\" OR mime_type : \"video\") AND tags : \"media\"" filter = "reference_uri = \"bishop://abc123--report.pdf\"" in: query required: false schema: type: string - name: order_by description: |- Comma-separated list of fields to sort by, with optional " asc" / " desc" suffix. Sortable fields: display_name, create_time, update_time, size_bytes, mime_type. Example: "create_time desc" or "display_name asc, size_bytes desc". Default: "display_name asc". in: query required: false schema: type: string tags: - Assets post: summary: Create Asset description: |- Register a new asset by linking an already-uploaded Bishop file to workspace/folder/tag metadata. See upload flow above. operationId: CreateAsset responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Asset" 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 requestBody: content: application/json: schema: $ref: "#/components/schemas/AssetServiceCreateAssetBody" required: true tags: - Assets "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/assets/{asset_id}": get: summary: Get Asset description: Get asset metadata by resource name. operationId: GetAsset responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Asset" 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: asset_id in: path required: true schema: type: string tags: - Assets patch: summary: Update Asset description: |- Update mutable asset fields: display_name, description, tags. Use MoveAsset to change the folder. Include "tags" in update_mask to replace or clear tags (see UpdateAssetRequest). operationId: UpdateAsset responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Asset" 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: asset_id in: path required: true schema: type: string - name: update_mask description: |- Field mask specifying which fields to update. Updatable fields: display_name, description, tags. Tag update semantics (via field mask): - Include "tags" in update_mask + provide asset.tags = ["a","b"] → replace all tags with ["a","b"] - Include "tags" in update_mask + provide asset.tags = [] → clear all tags - Omit "tags" from update_mask → leave tags unchanged Tags are compared case-insensitively; duplicates by case are dropped (the first one is kept). At most 20 tags; each 1-255 characters after trimming. in: query required: false schema: type: string requestBody: content: application/json: schema: type: object properties: display_name: type: string description: |- Human-readable display name for this asset (e.g., "Q1 Report.pdf"). Must be unique within the same folder (or workspace root) in the workspace. description: type: string description: Optional description. folder_name: type: string description: |- Resource name of the folder this asset belongs to. Empty means the asset is at the workspace root (no folder). file_name: type: string title: |- Reference to the underlying Bishop file (org-scoped file_id). Format: organizations/{organization}/files/{file} readOnly: true mime_type: type: string description: Server-detected MIME type of the uploaded file. readOnly: true size_bytes: type: string format: int64 description: Size of the file in bytes. readOnly: true tags: type: array items: type: string description: |- Free-form string labels attached to this asset. Tags are workspace-scoped — the same string may exist on multiple assets within a workspace. A single asset may carry multiple tags. Each tag is stored as provided (trimmed of surrounding whitespace), but tags are compared case-insensitively: "Finance" and "finance" are the same tag. Duplicates by case on one asset are dropped (the first one is kept). Limits: at most 20 tags per asset; each tag 1-255 characters after trimming. Tags are updatable via UpdateAsset (include "tags" in update_mask). Use ListWorkspaceTags to enumerate all tags in use within a workspace. created_by: type: string description: ID of the user who created this asset. readOnly: true create_time: type: string format: date-time description: Timestamp when the asset was created. readOnly: true update_time: type: string format: date-time description: Timestamp when the asset was last updated (renamed, moved, description changed, or tags changed). readOnly: true reference_uri: type: string description: |- This is an opaque, stable identity handle — NOT a publicly fetchable URL. It deliberately does not embed organization/workspace: callers must resolve those from their own request context (e.g. the parent they used to look up this asset), never by parsing them out of this string. Consumers pass it through bishop-url's parser and resolve it to bytes via the authenticated Asset/File services (e.g. GenerateAssetDownloadUrl). title: |- Canonical bishop:// handle that uniquely identifies this asset's underlying file. Format: bishop://{id}--{filename} e.g. bishop://ab12cd34--report.pdf readOnly: true title: The asset with updated fields. The name field identifies which asset. required: - display_name description: The asset with updated fields. The name field identifies which asset. required: true tags: - Assets delete: summary: Delete Asset description: Delete an asset (removes metadata and the underlying Bishop file). operationId: DeleteAsset responses: "200": description: A successful response. content: application/json: schema: type: object properties: {} 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: asset_id in: path required: true schema: type: string tags: - Assets "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/assets/{asset_id}:duplicate": post: summary: Duplicate Asset description: |- Duplicate an asset — creates a server-side file copy and a new asset record. The new asset's display_name is prefixed "Copy of "; the original is unchanged. Returns the newly created Asset. operationId: DuplicateAsset responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Asset" 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: asset_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/AssetServiceDuplicateAssetBody" required: true tags: - Assets "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/assets/{asset_id}:generateDownloadUrl": post: summary: Generate Asset Download Url description: |- Generate a presigned download URL for an asset. Delegates to Bishop FilesService.GenerateDownloadUrl. operationId: GenerateAssetDownloadUrl responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1GenerateAssetDownloadUrlResponse" 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: asset_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/AssetServiceGenerateAssetDownloadUrlBody" required: true tags: - Assets "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/assets/{asset_id}:move": post: summary: Move Asset description: Move an asset to a different folder (or to the workspace root). operationId: MoveAsset responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Asset" 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: asset_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/AssetServiceMoveAssetBody" required: true tags: - Assets "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/assets/{asset_id}:refreshContent": post: summary: Refresh Asset Content description: |- Refresh the asset's cached content fields — size_bytes, mime_type, update_time — from its backing file. operationId: RefreshAssetContent responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Asset" 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: asset_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/AssetServiceRefreshAssetContentBody" required: true tags: - Assets "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/assets/{asset_id}:traceAssetUsage": get: summary: Trace Asset Usage description: |- TraceAssetUsage returns all automations that reference a specific asset (file). Assets are read-only references, so no usage type is reported. An asset id is the underlying Bishop file id. Per AIP-136, this is a custom method using the :traceAssetUsage suffix. operationId: TraceAssetUsage responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1TraceAssetUsageResponse" 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: asset_id in: path required: true schema: type: string tags: - Assets "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/assets:batchDelete": post: summary: Batch Delete Assets description: |- Delete multiple assets in a single best-effort call. Each asset is deleted independently; per-item results are returned. operationId: BatchDeleteAssets responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1BatchDeleteAssetsResponse" 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 requestBody: content: application/json: schema: $ref: "#/components/schemas/AssetServiceBatchDeleteAssetsBody" required: true tags: - Assets "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/assets:batchDownload": post: summary: Batch Download Assets description: |- Build a ZIP archive of multiple assets and return a presigned download URL. Assets are collected independently; per-item errors are recorded without failing the overall request. operationId: BatchDownloadAssets responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1BatchDownloadAssetsResponse" 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 requestBody: content: application/json: schema: $ref: "#/components/schemas/AssetServiceBatchDownloadAssetsBody" required: true tags: - Assets "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/assets:batchDuplicate": post: summary: Batch Duplicate Assets description: |- Duplicate multiple assets in a single best-effort call. Each asset is duplicated independently; per-item results are returned. On success, the result name is the resource name of the new copy. operationId: BatchDuplicateAssets responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1BatchDuplicateAssetsResponse" 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 requestBody: content: application/json: schema: $ref: "#/components/schemas/AssetServiceBatchDuplicateAssetsBody" required: true tags: - Assets "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/assets:batchMove": post: summary: Batch Move Assets description: |- Move multiple assets to a destination folder in a single best-effort call. Each asset is moved independently; per-item results are returned. operationId: BatchMoveAssets responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1BatchMoveAssetsResponse" 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 requestBody: content: application/json: schema: $ref: "#/components/schemas/AssetServiceBatchMoveAssetsBody" required: true tags: - Assets "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/assets:tags": get: summary: List Workspace Tags description: |- List all unique tags in use across all assets in a workspace. Returns a deduplicated, sorted list of tag strings. Tags are compared case-insensitively, so each tag appears once regardless of case. Used to populate the Tags filter dropdown in the Library UI. operationId: ListWorkspaceTags responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ListWorkspaceTagsResponse" 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: - Assets "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/folders": get: summary: List Folders description: |- List folders in a workspace. Use parent_folder_name to list children of a folder. If parent_folder_name is empty, returns root-level folders. operationId: ListFolders responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ListFoldersResponse" 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: parent_folder_name description: |- If set, list only the immediate children of this folder. If empty, list only root-level folders. Format: organizations/{organization}/workspaces/{workspace}/folders/{folder} in: query required: false schema: type: string - name: page_size description: "Maximum number of folders to return. Default: 50." in: query required: false schema: type: integer format: int32 - name: page_token description: Page token from a previous ListFolders call. in: query required: false schema: type: string - name: order_by description: |- Comma-separated list of fields to sort by, with optional " asc" / " desc" suffix. Sortable fields: display_name, create_time, update_time. Example: "display_name asc" or "create_time desc". Default: "display_name asc". in: query required: false schema: type: string - name: filter description: |- AIP-160 filter expression. Filterable fields: display_name — string equality or substring: display_name = "Reports" or display_name : "rep" created_by — exact string equality: created_by = "user@example.com" Logical operators AND, OR, and parentheses are supported. Examples: filter = "display_name : \"report\"" filter = "created_by = \"alice@example.com\" AND display_name : \"2026\"" in: query required: false schema: type: string tags: - Folders post: summary: Create Folder description: Create a folder in a workspace. Set folder.parent_folder_name to nest it. operationId: CreateFolder responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Folder" 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: folder_id description: Optional client-provided folder ID (UUID). in: query required: false schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/v1Folder" description: |- The folder to create. To create a nested folder, set folder.parent_folder_name. required: true tags: - Folders "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/folders/{folder_id}": get: summary: Get Folder description: Get folder metadata by resource name. operationId: GetFolder responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Folder" 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: folder_id in: path required: true schema: type: string tags: - Folders patch: summary: Update Folder description: Update a folder (rename or move to a different parent). operationId: UpdateFolder responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Folder" 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: folder_id in: path required: true schema: type: string - name: update_mask description: |- Field mask specifying which fields to update. Updatable fields: display_name, parent_folder_name. in: query required: false schema: type: string requestBody: content: application/json: schema: type: object properties: display_name: type: string description: |- Human-readable display name for this folder (e.g., "Reports 2026"). Must be unique within the same parent folder in the same workspace. parent_folder_name: type: string title: |- Resource name of the parent folder, or empty if this is a root folder. Format: organizations/{organization}/workspaces/{workspace}/folders/{folder} created_by: type: string description: ID of the user who created this folder. readOnly: true create_time: type: string format: date-time description: Timestamp when the folder was created. readOnly: true update_time: type: string format: date-time description: Timestamp when the folder was last updated (renamed or moved). readOnly: true asset_count: type: integer format: int32 description: Number of assets directly contained in this folder (non-recursive). readOnly: true folder_count: type: integer format: int32 description: Number of immediate child folders (non-recursive). readOnly: true title: |- The folder with updated fields (display_name and/or parent_folder_name). The name field identifies which folder to update. required: - display_name description: |- The folder with updated fields (display_name and/or parent_folder_name). The name field identifies which folder to update. required: true tags: - Folders delete: summary: Delete Folder description: Delete a folder. Set force=true to recursively delete all contents. operationId: DeleteFolder responses: "200": description: A successful response. content: application/json: schema: type: object properties: {} 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: folder_id in: path required: true schema: type: string - name: force description: |- If true, recursively delete all sub-folders and assets within this folder. If false (default), returns FAILED_PRECONDITION if the folder is non-empty. in: query required: false schema: type: boolean tags: - Folders "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/folders/{folder_id}:duplicate": post: summary: Duplicate Folder description: |- Deep-duplicate a folder (including all descendant folders and assets). Asset files are copied server-side; no bytes transit the API. The root copy's display_name is prefixed "Copy of "; descendant names are unchanged. Returns the root Folder of the newly created subtree. operationId: DuplicateFolder responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Folder" 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: folder_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/AssetFolderServiceDuplicateFolderBody" required: true tags: - Folders "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/folders/{folder_id}:move": post: summary: Move Folder description: |- Move a folder to a new parent (reparent). Returns the updated Folder. Returns FAILED_PRECONDITION if the move would create a cycle. operationId: MoveFolder responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Folder" 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: folder_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/AssetFolderServiceMoveFolderBody" required: true tags: - Folders "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/folders:batchDelete": post: summary: Batch Delete Folders description: |- Delete multiple folders in a single best-effort call. Each folder is deleted independently; per-item results are returned. operationId: BatchDeleteFolders responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1BatchDeleteFoldersResponse" 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 requestBody: content: application/json: schema: $ref: "#/components/schemas/AssetFolderServiceBatchDeleteFoldersBody" required: true tags: - Folders "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/folders:batchDownload": post: summary: Batch Download Folders description: |- Build a ZIP archive of multiple folders (preserving relative structure) and return a presigned download URL. Folders are processed independently; per-item errors are recorded without failing the overall request. operationId: BatchDownloadFolders responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1BatchDownloadFoldersResponse" 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 requestBody: content: application/json: schema: $ref: "#/components/schemas/AssetFolderServiceBatchDownloadFoldersBody" required: true tags: - Folders "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/folders:batchDuplicate": post: summary: Batch Duplicate Folders description: |- Deep-duplicate multiple folders in a single best-effort call. Each folder (and its entire subtree) is duplicated independently. Per-item results are returned; on success the result name is the new root folder. operationId: BatchDuplicateFolders responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1BatchDuplicateFoldersResponse" 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 requestBody: content: application/json: schema: $ref: "#/components/schemas/AssetFolderServiceBatchDuplicateFoldersBody" required: true tags: - Folders "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/folders:batchMove": post: summary: Batch Move Folders description: |- Move multiple folders to a destination parent in a single best-effort call. Each folder is moved independently; per-item results are returned. operationId: BatchMoveFolders responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1BatchMoveFoldersResponse" 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 requestBody: content: application/json: schema: $ref: "#/components/schemas/AssetFolderServiceBatchMoveFoldersBody" required: true tags: - Folders "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/folders:tree": get: summary: Get Folder Tree description: Get the full folder tree for a workspace (all folders, nested). operationId: GetFolderTree responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1GetFolderTreeResponse" 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: - Folders "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/collections": get: summary: List Collections description: List collections in a workspace. operationId: ListCollections responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ListCollectionsResponse" 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: "Maximum number of collections to return. Default: 50." in: query required: false schema: type: integer format: int32 - name: page_token description: Page token from a previous ListCollections call. in: query required: false schema: type: string - name: order_by description: |- Comma-separated list of fields to sort by, with optional " asc" / " desc" suffix. Sortable fields: display_name, create_time, update_time. Example: "display_name asc" or "create_time desc". Default: "display_name asc". in: query required: false schema: type: string - name: filter description: |- AIP-160 filter expression. Filterable fields: display_name — string equality or substring: display_name = "Invoices" or display_name : "inv" created_by — exact string equality: created_by = "user@example.com" published — boolean equality: published = false (never published) has_unpublished_changes — boolean equality: has_unpublished_changes = true tags — has-tag check (: operator): tags : "finance" tags = "finance" is also accepted and behaves identically. Matching is case-insensitive: tags : "FINANCE" matches "Finance". Each term checks one tag; combine several with AND / OR. Logical operators AND, OR, and parentheses are supported. Examples: filter = "display_name : \"invoice\"" filter = "created_by = \"alice@example.com\" AND display_name : \"2026\"" filter = "tags : \"finance\" AND tags : \"quarterly\"" in: query required: false schema: type: string - name: stage description: |- The stage whose field_count and (approximate) record_count each returned collection reflects. Default (UNSPECIFIED): DRAFT. - COLLECTION_STAGE_UNSPECIFIED: Stage not specified. - COLLECTION_STAGE_DRAFT: The draft stage. - COLLECTION_STAGE_PUBLISHED: The published stage. in: query required: false schema: type: string enum: - COLLECTION_STAGE_UNSPECIFIED - COLLECTION_STAGE_DRAFT - COLLECTION_STAGE_PUBLISHED default: COLLECTION_STAGE_UNSPECIFIED tags: - Collections post: summary: Create Collection description: |- Create a collection in a workspace. body is "*" (not "collection") so the sibling `schema` input is bound too. operationId: CreateCollection responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Collection" 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 requestBody: content: application/json: schema: $ref: "#/components/schemas/CollectionsServiceCreateCollectionBody" required: true tags: - Collections "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/collections/{collection_id}": get: summary: Get Collection description: Get collection metadata by resource name. operationId: GetCollection responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Collection" 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: collection_id in: path required: true schema: type: string - name: stage description: |- Which stage to return schema and row-count for. Default (UNSPECIFIED): DRAFT — the schema editor always needs the live draft. - COLLECTION_STAGE_UNSPECIFIED: Stage not specified. - COLLECTION_STAGE_DRAFT: The draft stage. - COLLECTION_STAGE_PUBLISHED: The published stage. in: query required: false schema: type: string enum: - COLLECTION_STAGE_UNSPECIFIED - COLLECTION_STAGE_DRAFT - COLLECTION_STAGE_PUBLISHED default: COLLECTION_STAGE_UNSPECIFIED tags: - Collections patch: summary: Update Collection description: |- Update a collection's mutable fields (display_name, description, tags). Include "tags" in update_mask to replace or clear tags (see UpdateCollectionRequest). To edit the schema, use UpdateCollectionSchema (whole schema) or the field-level RPCs (AddCollectionField / UpdateCollectionField / DeleteCollectionField). operationId: UpdateCollection responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Collection" 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: collection_id in: path required: true schema: type: string - name: update_mask description: |- Field mask specifying which fields to update. Updatable fields: display_name, description, tags. Tag update semantics (via field mask): - Include "tags" in update_mask + provide collection.tags = ["a","b"] → replace all tags with ["a","b"] - Include "tags" in update_mask + provide collection.tags = [] → clear all tags - Omit "tags" from update_mask → leave tags unchanged Tags are compared case-insensitively; duplicates by case are dropped (the first one is kept). At most 20 tags; each 1-255 characters after trimming. To edit the schema, use UpdateCollectionSchema (whole schema) or the field-level RPCs (AddCollectionField / UpdateCollectionField / DeleteCollectionField). in: query required: false schema: type: string requestBody: content: application/json: schema: type: object properties: display_name: type: string description: |- Human-readable display name for this collection (e.g., "Customer Records"). Must be unique within the workspace. description: type: string description: Optional description of what this collection stores. schema_version: type: integer format: int32 description: |- Current schema version number (monotonically increasing). Schema versions start at 1 and increment with each schema edit (AddCollectionField / UpdateCollectionField / DeleteCollectionField). readOnly: true created_by: type: string description: ID of the user who created this collection. readOnly: true create_time: type: string format: date-time description: Timestamp when the collection was created. readOnly: true update_time: type: string format: date-time description: Timestamp when the collection was last updated (schema or metadata changed). readOnly: true reference_uri: type: string description: |- This is an opaque, stable identity handle resolved via the authenticated Collection service (rows are read through CollectionRowsService). title: |- Canonical bishop:// handle that uniquely identifies this collection. Format: bishop://collections/organizations/{organization}/workspaces/{workspace}/collections/{collection} readOnly: true record_count: type: string format: int64 description: |- Approximate total number of rows stored across all partitions of the collection. Derived from partition bookkeeping rather than a live scan, so it may overcount after row deletions. readOnly: true field_count: type: integer format: int32 description: |- Number of columns defined in the collection's current schema. Zero when the collection has no schema yet. readOnly: true stage: $ref: "#/components/schemas/v1CollectionStage" preview: $ref: "#/components/schemas/v1CollectionPreview" has_unpublished_changes: type: boolean description: Whether the draft schema has edits that are not yet published. readOnly: true tags: type: array items: type: string description: |- Free-form string labels attached to this collection. Tags are workspace-scoped — the same string may exist on multiple collections within a workspace. A single collection may carry multiple tags. Each tag is stored as provided (trimmed of surrounding whitespace), but tags are compared case-insensitively: "Finance" and "finance" are the same tag. Duplicates by case on one collection are dropped (the first one is kept). Limits: at most 20 tags per collection; each tag 1-255 characters after trimming. Tags may be set on CreateCollection and replaced via UpdateCollection (include "tags" in update_mask; an empty list clears all tags). Use ListCollectionTags to enumerate all tags in use within a workspace. title: The collection with updated fields. The name field identifies which collection. required: - display_name description: The collection with updated fields. The name field identifies which collection. required: true tags: - Collections delete: summary: Delete Collection description: Delete a collection. operationId: DeleteCollection responses: "200": description: A successful response. content: application/json: schema: type: object properties: {} 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: collection_id in: path required: true schema: type: string tags: - Collections "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/collections/{collection_id}/rows": post: summary: Insert Collection Row description: |- Insert a new row into a collection. Server assigns __row_id__ to the new row. operationId: InsertCollectionRow responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1InsertCollectionRowResponse" 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: collection_id in: path required: true schema: type: string - name: stage description: |- Which stage to target. Default (UNSPECIFIED): DRAFT. - COLLECTION_STAGE_UNSPECIFIED: Stage not specified. - COLLECTION_STAGE_DRAFT: The draft stage. - COLLECTION_STAGE_PUBLISHED: The published stage. in: query required: false schema: type: string enum: - COLLECTION_STAGE_UNSPECIFIED - COLLECTION_STAGE_DRAFT - COLLECTION_STAGE_PUBLISHED default: COLLECTION_STAGE_UNSPECIFIED requestBody: content: application/json: schema: type: object additionalProperties: $ref: "#/components/schemas/commonv1Value" description: |- Row data. Keys are column names; values carry their full Jarvis runtime type via `common.v1.Value`. Server assigns `__row_id__` to the new row. required: true tags: - Collections "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/collections/{collection_id}/rows/{row_id}": get: summary: Get Collection Row description: Get a single row by row_id. operationId: GetCollectionRow responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1GetCollectionRowResponse" 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: collection_id in: path required: true schema: type: string - name: row_id in: path required: true schema: type: string - name: stage description: |- Which stage to target. Default (UNSPECIFIED): DRAFT. - COLLECTION_STAGE_UNSPECIFIED: Stage not specified. - COLLECTION_STAGE_DRAFT: The draft stage. - COLLECTION_STAGE_PUBLISHED: The published stage. in: query required: false schema: type: string enum: - COLLECTION_STAGE_UNSPECIFIED - COLLECTION_STAGE_DRAFT - COLLECTION_STAGE_PUBLISHED default: COLLECTION_STAGE_UNSPECIFIED tags: - Collections patch: summary: Update Collection Row description: Update an existing row by row_id. operationId: UpdateCollectionRow responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1UpdateCollectionRowResponse" 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: collection_id in: path required: true schema: type: string - name: row_id in: path required: true schema: type: string - name: update_mask description: Columns to update. If omitted, every column in `row` is updated. in: query required: false schema: type: string - name: stage description: |- Which stage to target. Default (UNSPECIFIED): DRAFT. - COLLECTION_STAGE_UNSPECIFIED: Stage not specified. - COLLECTION_STAGE_DRAFT: The draft stage. - COLLECTION_STAGE_PUBLISHED: The published stage. in: query required: false schema: type: string enum: - COLLECTION_STAGE_UNSPECIFIED - COLLECTION_STAGE_DRAFT - COLLECTION_STAGE_PUBLISHED default: COLLECTION_STAGE_UNSPECIFIED requestBody: content: application/json: schema: type: object additionalProperties: $ref: "#/components/schemas/commonv1Value" description: |- Updated row data, keyed by column name. Values carry their full Jarvis runtime type via `common.v1.Value`. required: true tags: - Collections delete: summary: Delete Collection Row description: Delete a single row by row_id. operationId: DeleteCollectionRow responses: "200": description: A successful response. content: application/json: schema: type: object properties: {} 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: collection_id in: path required: true schema: type: string - name: row_id in: path required: true schema: type: string - name: stage description: |- Which stage to target. Default (UNSPECIFIED): DRAFT. - COLLECTION_STAGE_UNSPECIFIED: Stage not specified. - COLLECTION_STAGE_DRAFT: The draft stage. - COLLECTION_STAGE_PUBLISHED: The published stage. in: query required: false schema: type: string enum: - COLLECTION_STAGE_UNSPECIFIED - COLLECTION_STAGE_DRAFT - COLLECTION_STAGE_PUBLISHED default: COLLECTION_STAGE_UNSPECIFIED tags: - Collections "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/collections/{collection_id}/rows:batchDelete": post: summary: Batch Delete Collection Rows description: |- Delete multiple rows by __row_id__ in a single atomic call. Returns the number of rows deleted. operationId: BatchDeleteCollectionRows responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1BatchDeleteCollectionRowsResponse" 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: collection_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CollectionRowsServiceBatchDeleteCollectionRowsBody" required: true tags: - Collections "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/collections/{collection_id}/rows:batchInsert": post: summary: Batch Insert Collection Rows description: |- Insert multiple rows in a single atomic call. Returns the inserted rows with their server-assigned __row_id__. operationId: BatchInsertCollectionRows responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1BatchInsertCollectionRowsResponse" 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: collection_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CollectionRowsServiceBatchInsertCollectionRowsBody" required: true tags: - Collections "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/collections/{collection_id}/rows:exportCsv": post: summary: Export Collection description: |- Export all rows of a collection as a CSV file. Generates the CSV server-side, stores it, and returns a presigned download URL. operationId: ExportCollection responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ExportCollectionResponse" 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: collection_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CollectionRowsServiceExportCollectionBody" required: true tags: - Collections "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/collections/{collection_id}/rows:importCsv": post: summary: Import Collection description: |- Import rows into a collection from a previously-uploaded Bishop file. The caller first uploads the source file to Bishop (e.g. via FilesHttpService.UploadFile) and passes its Bishop file URL as `source_uri`. The service downloads the file, parses it (CSV), and bulk inserts the parsed rows. When the target collection has no schema yet, the schema is inferred from the file's columns and stored as a new version. operationId: ImportCollection responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ImportCollectionResponse" 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: collection_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CollectionRowsServiceImportCollectionBody" required: true tags: - Collections "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/collections/{collection_id}/rows:query": post: summary: List Collection Rows description: List rows from a collection with pagination and filtering. operationId: ListCollectionRows responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ListCollectionRowsResponse" 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: collection_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CollectionRowsServiceListCollectionRowsBody" required: true tags: - Collections "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/collections/{collection_id}/schema": get: summary: Get Collection Schema description: Get a collection's current schema for a stage. Defaults to the DRAFT stage. operationId: GetCollectionSchema responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1CollectionSchema" 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: collection_id in: path required: true schema: type: string - name: stage description: |- Which stage's current schema to return. Default (UNSPECIFIED): DRAFT. - COLLECTION_STAGE_UNSPECIFIED: Stage not specified. - COLLECTION_STAGE_DRAFT: The draft stage. - COLLECTION_STAGE_PUBLISHED: The published stage. in: query required: false schema: type: string enum: - COLLECTION_STAGE_UNSPECIFIED - COLLECTION_STAGE_DRAFT - COLLECTION_STAGE_PUBLISHED default: COLLECTION_STAGE_UNSPECIFIED tags: - Collections "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/collections/{collection_id}:addField": post: summary: Add Collection Field description: |- Add a single field (column) to a collection's schema. Creates a new schema version; returns the resulting current schema. Returns ALREADY_EXISTS if a field with the same name already exists. operationId: AddCollectionField responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1CollectionSchema" 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: collection_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CollectionsServiceAddCollectionFieldBody" required: true tags: - Collections "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/collections/{collection_id}:deleteField": post: summary: Delete Collection Field description: |- Delete a single field (column) from a collection's schema. Creates a new schema version; returns the resulting current schema. Returns NOT_FOUND if the named field does not exist. operationId: DeleteCollectionField responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1CollectionSchema" 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: collection_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CollectionsServiceDeleteCollectionFieldBody" required: true tags: - Collections "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/collections/{collection_id}:publish": post: summary: Publish Collection description: Promote the draft stage to published. operationId: PublishCollection responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1PublishCollectionResponse" 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: collection_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CollectionsServicePublishCollectionBody" required: true tags: - Collections "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/collections/{collection_id}:traceCollectionUsage": get: summary: Trace Collection Usage description: |- TraceCollectionUsage returns all automations that use a specific collection, along with how each one uses it (read or write). Usage is derived from the collection access methods recorded in the automation's code manifest; any write access classifies the collection as write. Per AIP-136, this is a custom method using the :traceCollectionUsage suffix. operationId: TraceCollectionUsage responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1TraceCollectionUsageResponse" 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: collection_id in: path required: true schema: type: string tags: - Collections "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/collections/{collection_id}:updateField": post: summary: Update Collection Field description: |- Update a single field (column) in a collection's schema. Creates a new schema version; returns the resulting current schema. Returns NOT_FOUND if the named field does not exist. operationId: UpdateCollectionField responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1CollectionSchema" 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: collection_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CollectionsServiceUpdateCollectionFieldBody" required: true tags: - Collections "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/collections/{collection_id}:updateSchema": post: summary: Update Collection Schema description: |- Replace a collection's whole schema in one call. Creates a new schema version; returns the resulting current schema. The change is gated by the same backward-compatibility check as the field-level edits (rejects incompatible changes with FAILED_PRECONDITION). operationId: UpdateCollectionSchema responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1CollectionSchema" 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: collection_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CollectionsServiceUpdateCollectionSchemaBody" required: true tags: - Collections "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/collections:batchTraceCollectionUsage": post: summary: Batch Trace Collection Usage description: |- BatchTraceCollectionUsage is TraceCollectionUsage for many collections at once, so a list of collections can show usage without one call per collection. operationId: BatchTraceCollectionUsage responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1BatchTraceCollectionUsageResponse" 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 requestBody: content: application/json: schema: $ref: "#/components/schemas/AutomationServiceBatchTraceCollectionUsageBody" required: true tags: - Collections "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/workItems": get: summary: List Work Items description: |- ListWorkItems lists the items in a workspace, with filtering, ordering and pagination. Every view a surface offers is composed from this one method. input_form is left unset on every item here to avoid repeating potentially large schemas. Surfaces rendering forms alongside queue rows fetch GetWorkItem for the items being reviewed. operationId: ListWorkItems responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ListWorkItemsResponse" 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 items to return. The service may return fewer. If unspecified, at most 50 items are returned. The maximum is 1000; values above 1000 are coerced to 1000. in: query required: false schema: type: integer format: int32 - name: page_token description: |- The page token received from a previous ListWorkItems call. When paginating, all other parameters must match the call that provided it. in: query required: false schema: type: string - name: filter description: |- An AIP-160 filter expression. Filterable fields, with the operators each admits: kind = != assignee, labels.* = != :* create_time, update_time = != < <= > >= has_units_with_status(STATUS, ...) is true when every supplied status has at least one attached unit. Different units satisfy different statuses. Accepts one or more WorkUnitStatus names without the WORK_UNIT_STATUS_ prefix, excluding UNSPECIFIED. Repeated statuses are deduplicated. Empty arguments, unknown statuses and non-status expressions are INVALID_ARGUMENT. Use OR between calls to match either status, for example: has_units_with_status(WAITING_FOR_INPUT) OR has_units_with_status(PROCESSING) Mixed work can be selected with has_units_with_status(WAITING_FOR_INPUT, ANSWERED). The function composes with AND, OR and NOT. An item with no units matches no positive call. Nested functions and count comparisons are unsupported. Filtering selects items, never narrows their returned unit_counts. Anything else is INVALID_ARGUMENT, including an ordered comparison on a label and any field not listed. Unassigned is `NOT assignee:*`. assignee takes a resource name — `users/{user_id}`, the value this API returns — and a bare identifier is INVALID_ARGUMENT rather than a filter that matches nothing. A label filter matches the grouping labels recorded when the item was created, not a unit's labels as they stand now; the two can differ, and `ListWorkUnits` is where the current ones are. `labels.k:*` matches only an item whose first unit supplied k, and an item whose first unit supplied none of the kind's grouping keys matches no label filter at all. An item whose grouping key was omitted matches neither `labels.k = "v"` nor `labels.k != "v"`; use `NOT labels.k:*` for absence. A label filter names one of the kind's grouping labels, which is what an item is identified by, and is served by an index. Any other label belongs to a unit rather than to the item: it is not projected onto the item and no item filter reaches it, so such a filter selects nothing. Filter a unit's own labels through ListWorkUnits. in: query required: false schema: type: string - name: order_by description: |- Comma-separated ordering by create_time or update_time, each ascending (asc, the default) or descending (desc). Defaults to create_time ascending, oldest item first. Ties break by item name ascending. Other fields, including archive_time, unit_count and settle_time, are INVALID_ARGUMENT. in: query required: false schema: type: string tags: - Work Items "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/workItems/{work_item_id}": get: summary: Get Work Item description: |- GetWorkItem retrieves one item: its question, the shared human-input form, the labels that define it and how much it covers. Final submissions belong to units; delivery outcomes are independent of unit settlement. operationId: GetWorkItem responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1WorkItem" 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: work_item_id in: path required: true schema: type: string tags: - Work Items "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/workItems/{work_item_id}:archive": post: summary: Archive Work Item description: |- ArchiveWorkItem archives a persistent item and locally dismisses its unresolved units. New arrivals and units rekeyed into it are also dismissed. Requires a dismissible kind; items without unresolved units may be archived. Answered and withdrawn units retain their outcomes. Assignment is unchanged. No source decision or delivery is created; archival controls attention only. operationId: ArchiveWorkItem responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1WorkItem" 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: work_item_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/WorkItemServiceArchiveWorkItemBody" required: true tags: - Work Items "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/workItems/{work_item_id}:assign": post: summary: Assign Work Item description: |- AssignWorkItem assigns an item to a person, or returns it to unassigned when the assignee is empty. Requires a non-archived item with at least one unresolved unit; otherwise returns FAILED_PRECONDITION. Assignment does not restrict who may answer. operationId: AssignWorkItem responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1WorkItem" 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: work_item_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/WorkItemServiceAssignWorkItemBody" required: true tags: - Work Items "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/workItems/{work_item_id}:decline": post: summary: Decline Assignment description: |- DeclineAssignment hands an item back with a reason, returning it to unassigned. Requires a non-archived item with at least one unresolved unit; otherwise returns FAILED_PRECONDITION. Unit states are unchanged. operationId: DeclineAssignment responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1WorkItem" 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: work_item_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/WorkItemServiceDeclineAssignmentBody" required: true tags: - Work Items "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/workItems/{work_item_id}:markPreparationStarted": post: summary: Mark Work Item Preparation Started description: |- MarkWorkItemPreparationStarted clears the item's preparation_required flag. Clients call this after Rain accepts the preparation prompt. This operation neither starts an agent nor asserts preparation succeeded. Already-clear items succeed. There is no concurrency token: a delayed clear can clear a flag set by a newer arrival. Final submissions and approval are unaffected. operationId: MarkWorkItemPreparationStarted responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1WorkItem" 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: work_item_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/WorkItemServiceMarkWorkItemPreparationStartedBody" required: true tags: - Work Items "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/workItems/{work_item_id}:setInputForm": post: summary: Set Work Item Input Form description: |- SetWorkItemInputForm creates or replaces the shared human-input form. Requires the current input_form_etag; mismatch returns ABORTED. An identical form is a no-op after checking the etag. Unsupported forms return INVALID_ARGUMENT. The form is required; this operation does not remove it. Resolve option references separately against each unit's immutable evidence. Missing or invalid choices become empty selections without rejecting the shared form or blocking other fields or units. Carry values into each unresolved unit's new draft only for matching field keys whose values validate against the new field; do not coerce values. Drop other values. Previous forms and responses are not retained. Clear acceptance, rotate response etags and set WAITING_FOR_INPUT atomically. Settled units retain their input and status, including on archived items. New unresolved units use the latest form. No per-unit opt-out exists. Serialize with admission, rekey, acceptance and final submission: a committed submission stays final; a form change committed first invalidates old etags. operationId: SetWorkItemInputForm responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1WorkItem" 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: work_item_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/WorkItemServiceSetWorkItemInputFormBody" required: true tags: - Work Items "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/workItems/{work_item_id}:unarchive": post: summary: Unarchive Work Item description: |- UnarchiveWorkItem ends persistent archival and restores locally dismissed units, excluding answered and source/operator-withdrawn occurrences. Restore against the latest input form, retaining only matching field keys with valid values, without coercion or historical copies. Clear input when no form exists. Clear acceptance and rotate response etags. Restored units wait for input when a form exists, otherwise enter PROCESSING. Clear archive_time, retain assignment and allow future arrivals. No source decision or delivery is created or reversed. operationId: UnarchiveWorkItem responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1WorkItem" 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: work_item_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/WorkItemServiceUnarchiveWorkItemBody" required: true tags: - Work Items "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/workItems:stream": get: summary: Subscribe Work Items description: Subscribe to item changes throughout one workspace, independent of list filters. operationId: SubscribeWorkItems responses: "200": description: A successful response.(streaming responses) content: application/json: schema: type: object properties: result: $ref: "#/components/schemas/v1WorkItemUpdate" error: $ref: "#/components/schemas/rpcStatus" title: Stream result of v1WorkItemUpdate 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: - Work Items "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/workUnits": get: summary: List Work Units description: |- ListWorkUnits lists workspace units and, per unit, whether the answer took effect. Each unit carries the same fields as GetWorkUnit, including evidence and answer_form, input and answer_draft. Choose page_size to keep the complete response within transport limits. operationId: ListWorkUnits responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ListWorkUnitsResponse" 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 units to return. The service may return fewer. If unspecified, at most 50 units are returned. The maximum is 1000; values above 1000 are coerced to 1000. in: query required: false schema: type: integer format: int32 - name: page_token description: The page token received from a previous ListWorkUnits call. in: query required: false schema: type: string - name: filter description: |- An AIP-160 filter expression over workspace units. An empty filter lists all units, including occurrences with no work item. Filterable fields, with the operators each admits: work_item = != :* kind, source_ref, occurrence_id = != correlation_id = != :* status = != labels.* = != :* create_time, update_time = != < <= > >= settle_time = != < <= > >= :* Anything else is INVALID_ARGUMENT, including an ordered comparison on a label and any field not listed. assignee and delivery.outcome are not filterable; every unit returned carries its own delivery. correlation_id is scoped by the workspace; include kind when looking up related requests from one source kind. Uncorrelated units match neither equality nor inequality; use NOT correlation_id:* for absence. work_item compares a full WorkItem resource name, including its workspace; a bare identifier is INVALID_ARGUMENT. Units without an item match neither equality nor inequality; use NOT work_item:* for absence. A label filter matches the unit's labels as they stand now. A unit that does not carry the label matches neither `labels.k = "v"` nor `labels.k != "v"`; use `NOT labels.k:*` for absence. Unresolved units have status WAITING_FOR_INPUT or PROCESSING and no settle_time. in: query required: false schema: type: string - name: order_by description: |- How to order the results. Orderable fields: create_time, update_time, settle_time, each ascending or descending. Defaults to create_time ascending. Ties break by name, so a page boundary neither repeats nor skips a unit sharing a timestamp with another. in: query required: false schema: type: string tags: - Work Items "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/workUnits/submissions:batchCreate": post: summary: Batch Create Submissions description: |- BatchCreateSubmissions applies a shared answer or each selected unit's saved draft. All selected submissions and delivery obligations commit together or none do. Validate and normalize independently for each unit; response order matches work_units. New arrivals outside the selection receive no decision. Reject duplicate names, empty selection, malformed names or a unit whose workspace differs from parent with INVALID_ARGUMENT before writes. work_item must name an item in parent. Verify every selected unit's stored membership in work_item atomically with submission; a mismatch returns FAILED_PRECONDITION. A resource name alone does not establish membership. If any unit is already answered, return ABORTED with the conflict count and first conflicting submission. Read selected units for the remaining submission references; error metadata is bounded. Dismissed/withdrawn units return FAILED_PRECONDITION. Any failure writes nothing for the entire selection. operationId: BatchCreateSubmissions responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1BatchCreateSubmissionsResponse" 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 requestBody: content: application/json: schema: $ref: "#/components/schemas/SubmissionServiceBatchCreateSubmissionsBody" required: true tags: - Work Items "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/workUnits/{work_unit_id}": get: summary: Get Work Unit description: |- GetWorkUnit retrieves one unit in full, including the evidence behind it and whether its decision took effect. operationId: GetWorkUnit responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1WorkUnit" 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: work_unit_id in: path required: true schema: type: string tags: - Work Items "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/workUnits/{work_unit_id}/submissions": post: summary: Create Submission description: |- CreateSubmission answers one unit. Acceptance, submission and delivery obligation commit atomically; publication and source application are later. Validate the unit's immutable answer_form and normalize before writes. Human input is optional, even when the item has an input_form. Validate independently of intermediate input. Alternatively consume the exact answer_draft_etag; do not supply direct values in this mode. Successful submission clears the draft in either mode. A direct answer does not check the draft token. Serialize with rekey and settlement. Require an authenticated user; derive submitter from trusted context. ABORTED identifies the existing submission if already answered, even when the repeated request has identical values. Dismissed or withdrawn units return FAILED_PRECONDITION. Invalid values return INVALID_ARGUMENT. operationId: CreateSubmission responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Submission" 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: work_unit_id in: path required: true schema: type: string - name: answer_draft_etag description: |- Submit exactly this saved draft. Stale drafts return ABORTED. Both modes clear the draft atomically on success; failed submissions retain it. in: query required: false schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/v1Submission" description: |- For a direct answer, only submission.answer is supplied; metadata and name are server-derived. Supply submission.answer or answer_draft_etag, exactly one. Direct answers bypass draft storage and do not require the current draft's etag. required: true tags: - Work Items "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/workUnits/{work_unit_id}/submissions/{submission_id}": get: summary: Get Submission description: |- GetSubmission returns the exact unit-scoped final answer, never response history or a bulk aggregate. Submissions cannot be updated or deleted. operationId: GetSubmission responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Submission" 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: work_unit_id in: path required: true schema: type: string - name: submission_id in: path required: true schema: type: string tags: - Work Items "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/workUnits/{work_unit_id}:acceptInput": post: summary: Accept Work Unit Input description: |- AcceptWorkUnitInput explicitly accepts the current complete human response. Validate and normalize against the unit's resolved input.form; missing required fields fail. Record the authenticated actor and time, change etag and set PROCESSING. Revoke acceptance before editing again. This creates no final submission. Requires a matching etag; stale etags return ABORTED. Settled units or an absent item input_form return FAILED_PRECONDITION. Invalid values return INVALID_ARGUMENT. Attribution alone does not establish that the caller is a human. operationId: AcceptWorkUnitInput responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1WorkUnit" 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: work_unit_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/WorkItemServiceAcceptWorkUnitInputBody" required: true tags: - Work Items "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/workUnits/{work_unit_id}:revokeInputAcceptance": post: summary: Revoke Work Unit Input Acceptance description: |- RevokeWorkUnitInputAcceptance clears acceptance without changing values, changes etag and sets WAITING_FOR_INPUT. No final decision is created. Requires a published item input_form and matching response etag. Stale etags return ABORTED; settled units or an absent item input_form return FAILED_PRECONDITION. operationId: RevokeWorkUnitInputAcceptance responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1WorkUnit" 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: work_unit_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/WorkItemServiceRevokeWorkUnitInputAcceptanceBody" required: true tags: - Work Items "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/workUnits/{work_unit_id}:saveAnswer": post: summary: Save Work Unit Answer description: |- SaveWorkUnitAnswer replaces an optional final-answer draft. Required fields may be omitted; supplied values validate against the unit's answer_form. Empty values clear the draft. Requires the current answer_draft.etag; stale tokens return ABORTED. Settled units return FAILED_PRECONDITION. Saving changes neither status nor input acceptance and creates no delivery. operationId: SaveWorkUnitAnswer responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1WorkUnit" 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: work_unit_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/WorkItemServiceSaveWorkUnitAnswerBody" required: true tags: - Work Items "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/workUnits/{work_unit_id}:saveInput": post: summary: Save Work Unit Input description: |- SaveWorkUnitInput replaces the complete draft value map, not a final answer. Requires a published item input_form and matching response etag. Drafts may omit required fields; supplied values must validate. Empty clears the draft. Accepted input returns FAILED_PRECONDITION, even when values are equal; revoke acceptance before editing. Successful saves remain WAITING_FOR_INPUT. No submission or delivery is created. Stale etags return ABORTED; an absent item input_form or settled units return FAILED_PRECONDITION; invalid values return INVALID_ARGUMENT. Empty selections do not prevent saving other fields. Validate against the unit's resolved input form under its current item lock. operationId: SaveWorkUnitInput responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1WorkUnit" 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: work_unit_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/WorkItemServiceSaveWorkUnitInputBody" required: true tags: - Work Items "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/workUnits:stream": get: summary: Subscribe Work Units description: |- Subscribe to units entering, changing within or leaving one item. Status is never filtered: answered, dismissed and withdrawn updates are included. operationId: SubscribeWorkUnits responses: "200": description: A successful response.(streaming responses) content: application/json: schema: type: object properties: result: $ref: "#/components/schemas/v1WorkUnitUpdate" error: $ref: "#/components/schemas/rpcStatus" title: Stream result of v1WorkUnitUpdate 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: work_item description: Item membership to observe. Must belong to parent. in: query required: true schema: type: string tags: - Work Items "/api/v1/workItemKinds": get: summary: List Work Item Kinds description: |- ListWorkItemKinds lists every kind with the part of its descriptor a client needs: the label to show and the keys that group its units. Retired kinds are listed, and carry `retire_time`. No new work of such a kind will arrive. The registry is small and read whole, so a client fetches this once and caches it rather than resolving a kind per item. That is why there is no GetWorkItemKind. A cached entry may become retired, and a retired one may return to effect. Kinds are registered platform-wide rather than per tenant, so this collection has no parent. operationId: ListWorkItemKinds responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ListWorkItemKindsResponse" default: description: An unexpected error response. content: application/json: schema: $ref: "#/components/schemas/rpcStatus" parameters: - name: page_size description: |- The maximum number of kinds to return. Defaults to the whole registry, which is expected to stay small. in: query required: false schema: type: integer format: int32 - name: page_token description: A page token from a previous response. in: query required: false schema: type: string tags: - Work Items "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/guides": get: summary: List Guides description: |- ListGuides lists the guides in a workspace. Disabled guides are excluded unless include_disabled=true. Optional work_item restricts discovery to one item; the consuming agent interprets each returned guide's scope. Search results do not establish applicability. operationId: ListGuides responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ListGuidesResponse" 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 guides to return. The service may return fewer. in: query required: false schema: type: integer format: int32 - name: page_token description: The page token received from a previous ListGuides call. in: query required: false schema: type: string - name: filter description: |- An AIP-160 filter over state, create_time and update_time, plus text:"…", which searches title, body and scope. The owning item's kind supports work_item.kind = / !=; its grouping labels support work_item.labels. = / != / :*. For example: work_item.kind = "source.failure" AND work_item.labels.process_id = "A" Label predicates read the item's immutable grouping identity, not its units or guide examples. Keys and values are opaque to Workbench. Omitted keys leave other grouping dimensions unrestricted; non-grouping keys match nothing. Missing/null labels match neither equality nor inequality; use NOT work_item.labels.:* for absence. Per-occurrence items have no grouping labels. Empty or archived items remain discoverable. These predicates compose with AND, OR and NOT, and with work_item and include_disabled, before counting and pagination. A state filter does not override include_disabled: filtering for DISABLED requires it to be true. in: query required: false schema: type: string - name: order_by description: |- Orderable fields: create_time, update_time. Defaults to update_time descending, with resource name as the tie-breaker. in: query required: false schema: type: string - name: work_item description: |- Restrict results to guides belonging to this item. Omitted lists guides across the workspace. Must name an item in parent; wrong scope is INVALID_ARGUMENT. Combines with filter and include_disabled. in: query required: false schema: type: string - name: include_disabled description: Include disabled guides for management. Defaults to false. in: query required: false schema: type: boolean tags: - Guides post: summary: Create Guide description: |- CreateGuide saves guidance for an existing item in the parent workspace. Defaults to REVIEW_REQUIRED. Multiple guides may belong to the same item. Requires an authenticated author; no proposal or draft is stored. operationId: CreateGuide responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Guide" 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 requestBody: content: application/json: schema: $ref: "#/components/schemas/v1Guide" description: The guide to write. required: true tags: - Guides "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/guides/{guide_id}": get: summary: Get Guide description: GetGuide retrieves one guide, including disabled guides. operationId: GetGuide responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Guide" 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: guide_id in: path required: true schema: type: string tags: - Guides patch: summary: Update Guide description: |- UpdateGuide changes content or state using an explicit mask and current guide.etag. Missing etag is INVALID_ARGUMENT; stale etag is ABORTED. work_item is immutable. Input acceptance and submission remain separate. operationId: UpdateGuide responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1Guide" 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: guide_id in: path required: true schema: type: string - name: update_mask description: |- Explicit nonempty mask over title, body, scope, examples and state. work_item is immutable; etag is a precondition, not a mutable field. Updating examples replaces the entire list. Other paths are rejected. in: query required: true schema: type: string requestBody: content: application/json: schema: type: object properties: work_item: type: string description: |- Persistent item this guidance belongs to, in the same workspace. Required on creation and immutable. Rekey does not move or copy guides. scope: type: string description: |- Free-text applicability conditions interpreted by the consuming agent. Empty means no additional conditions beyond belonging to this item. state: $ref: "#/components/schemas/v1GuideState" title: type: string description: Short title for discovery and display. body: type: string description: Free-text resolution instructions. Interpretation belongs to the reader. examples: type: array items: $ref: "#/components/schemas/v1GuideExample" description: |- Supporting units, with optional explanations. Updating this field replaces the entire list; referenced units are never modified or deleted. etag: type: string description: |- Server-issued concurrency token. Ignored on creation; required on update. Supply the current value without including etag in update_mask. A successful change rotates it; a mismatch returns ABORTED. sources: type: array items: $ref: "#/components/schemas/v1GuideSource" description: Read-only reference sources in the same workspace. Updating replaces the list. created_by: type: string title: |- Who wrote it, and who last changed it. Who changed it before that is an audit trail and belongs to vigil. Format: users/{user_id} readOnly: true updated_by: type: string title: "Format: users/{user_id}" readOnly: true create_time: type: string format: date-time description: The time the guide was written. readOnly: true update_time: type: string format: date-time description: The time it last changed. readOnly: true title: The guide, carrying its resource name, current etag and fields to change. required: - work_item - title - body description: The guide, carrying its resource name, current etag and fields to change. required: true tags: - Guides delete: summary: Delete Guide description: |- DeleteGuide permanently removes a guide and its example associations. Referenced units are unchanged. No restore API is provided; use DISABLED for reversible removal from discovery. Requires current etag; a missing etag is INVALID_ARGUMENT and a stale etag is ABORTED. Deletion emits an audit event. operationId: DeleteGuide responses: "200": description: A successful response. content: application/json: schema: type: object properties: {} 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: guide_id in: path required: true schema: type: string - name: etag description: Current Guide.etag. A stale value returns ABORTED. in: query required: true schema: type: string tags: - Guides "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/guides:batchUpdate": post: summary: Batch Update Guides description: |- BatchUpdateGuides atomically applies masked edits in one workspace. Any invalid request, missing guide or stale etag leaves every guide unchanged. Authorization uses the same-named workspace RPC permission, as other methods. operationId: BatchUpdateGuides responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1BatchUpdateGuidesResponse" 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 requestBody: content: application/json: schema: $ref: "#/components/schemas/GuideServiceBatchUpdateGuidesBody" required: true tags: - Guides "/api/v1/organizations/{organization_id}/auditEvents": get: summary: List Audit Events description: |- ListAuditEvents lists audit events, newest first. Supports AIP-160 filtering (event_type, category, actor, workspace_id, event_time range, status, credits_delta) and keyset pagination. Audit logs are an org-level object: this single org-scoped endpoint serves every caller, and the server RBAC-filters the returned rows by the caller's roles across the org (org owners see every tier across all workspaces; workspace admins/authors see their workspaces' events at their tier). Workspace is a `workspace_id` filter, not a path. operationId: ListAuditEvents responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ListAuditEventsResponse" 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 events to return. The service may return fewer. If unspecified, at most 50 are returned; the maximum is 1000. in: query required: false schema: type: integer format: int32 - name: page_token description: |- A page token from a previous ListAuditEvents call. Provide it to retrieve the subsequent page. Keyset-based: encodes (event_time, id) of the last row. in: query required: false schema: type: string - name: filter description: |- An AIP-160 filter expression. Supported fields: event_type, category, actor, workspace_id, event_time (range), status, credits_delta. in: query required: false schema: type: string - name: order_by description: |- Sort order. Only "event_time desc" (default) and "event_time asc" are supported; the keyset cursor follows the chosen order. in: query required: false schema: type: string tags: - Audit Events "/api/v1/organizations/{organization_id}/auditEvents/{audit_event_id}": get: summary: Get Audit Event description: |- GetAuditEvent retrieves a single audit event by resource name. Backs the "copy link to this event" deep-link in the UI. The server applies the same RBAC row-filtering as ListAuditEvents and returns NOT_FOUND (never PERMISSION_DENIED) when the event is outside the caller's visibility, so existence is not disclosed. operationId: GetAuditEvent responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1AuditEvent" 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: audit_event_id in: path required: true schema: type: string tags: - Audit Events "/api/v1/organizations/{organization_id}/auditEvents:export": post: summary: Export Audit Events description: |- ExportAuditEvents generates a downloadable export (e.g. CSV) of the audit events matching a filter, returning a short-lived presigned URL. Applies the same org-level RBAC row-filtering as ListAuditEvents. operationId: ExportAuditEvents responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/v1ExportAuditEventsResponse" 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/AuditServiceExportAuditEventsBody" required: true tags: - Audit Events servers: - url: https://app.us-1.kognitos.com components: securitySchemes: BearerAuth: type: http scheme: bearer description: 'Personal Access Token.' schemas: v1QueryAutomationRunAggregatesResponse: type: object properties: automation_run_aggregates: type: array items: $ref: "#/components/schemas/v1AutomationRunAggregateEntry" description: List of automation run statistics entries. readOnly: true description: |- Response message for QueryAutomationRunAggregates method. Contains statistics for each automation in the workspace. v1AutomationRunAggregateEntry: type: object properties: automation_id: type: string title: >- The automation ID for this entry. Format: organizations/{organization}/workspaces/{workspace}/automations/{automation} readOnly: true stats: $ref: "#/components/schemas/v1AutomationRunAggregate" description: |- Entry for automation run statistics. Contains the automation ID and its associated run counts. v1AutomationRunAggregate: type: object properties: total_runs: type: string format: int64 description: The total number of runs for this automation. readOnly: true completed_runs: type: string format: int64 description: The number of completed runs for this automation. readOnly: true description: |- Stats for a single automation. Contains run counts and other metrics. v1ListWorkspaceRolesResponse: type: object properties: roles: type: array items: $ref: "#/components/schemas/v1Role" description: |- The list of roles in the workspace. Includes both system-defined role templates (named roleTemplates/{id}) and the workspace's custom roles (named organizations/{org}/workspaces/{ws}/customRoles/{id}, with `custom` set). 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. 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) description: |- List responses also use this message for entries that are not concrete role instances, in which case `name` carries the referenced resource: roleTemplates/{role_template} for system-defined templates organizations/{organization}/workspaces/{workspace}/customRoles/{custom_role} for workspace custom roles, which additionally set `custom`. These are not declared as patterns above because AIP-123 requires every pattern'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. Format: "{action}:{resource_path}" (e.g., "GET:/api/v1/me") readOnly: true description: |- Superseded by `permission_details`, which carries these same strings plus their display metadata; this field is slated for removal in the next major version. It is not yet marked `deprecated` because clients cannot migrate until Agora populates `permission_details` — do that first, then flip the option, 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 system-defined role template. Lets clients tell the two apart without parsing `name`. permission_details: type: array items: $ref: "#/components/schemas/v1RolePermission" description: |- The permissions this role grants, with the display metadata needed to render them. Supersedes `permissions`, which carries the same strings without it. `RolePermission.permission` is self-sufficient — it is the same "{action}:{resource_path}" string — so a client needs only this field. Keyed by the permission string rather than positional: entries correspond to `permissions` by `RolePermission.permission`, not by index. An entry may be absent when a permission has no backing template metadata, so a client must fall 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. Roles can be created from RoleTemplates or as standalone custom roles. required: - title v1ListAutomationTriggersResponse: type: object properties: automation_triggers: type: array items: $ref: "#/components/schemas/v1AutomationTrigger" description: List of triggers that are active for the specified automation. next_page_token: type: string description: |- A token that can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no subsequent pages. description: Response containing the list of active triggers for an automation. v1AutomationTrigger: type: object properties: trigger_id: type: string description: |- The external trigger ID created by another service. This ID uniquely identifies the trigger in the external system. automation: type: string title: >- Reference to the automation to be triggered. Format: organizations/{organization}/workspaces/{workspace}/automations/{automation} readOnly: true input_mapping: type: object additionalProperties: type: string description: >- Input mapping for the automation execution. Keys are input parameter names, values are the corresponding values to pass. phase_type: $ref: "#/components/schemas/v1PhaseType" phase_sub_type: $ref: "#/components/schemas/v1PhaseSubType" is_active: type: boolean description: Whether this trigger is currently active. description: >- AutomationTrigger represents phase configuration metadata for an external trigger. The trigger itself is created and managed by another service; this message stores additional metadata about how the trigger relates to automation phases. required: - trigger_id - phase_type v1PhaseType: type: string enum: - PHASE_TYPE_UNSPECIFIED - PHASE_TYPE_PRE - PHASE_TYPE_MAIN - PHASE_TYPE_POST default: PHASE_TYPE_UNSPECIFIED description: |- PhaseType defines the type of phase for an automation trigger. - PHASE_TYPE_UNSPECIFIED: Unspecified phase type. - PHASE_TYPE_PRE: Pre-processing phase. - PHASE_TYPE_MAIN: Main processing phase. - PHASE_TYPE_POST: Post-processing phase. v1PhaseSubType: type: string enum: - PHASE_SUB_TYPE_UNSPECIFIED - PHASE_SUB_TYPE_EMAIL - PHASE_SUB_TYPE_SCHEDULE - PHASE_SUB_TYPE_WEBHOOK - PHASE_SUB_TYPE_API default: PHASE_SUB_TYPE_UNSPECIFIED description: >- PhaseSubType defines the sub-type within a phase for an automation trigger. - PHASE_SUB_TYPE_UNSPECIFIED: Unspecified phase sub-type. - PHASE_SUB_TYPE_EMAIL: Email trigger sub-type. - PHASE_SUB_TYPE_SCHEDULE: Schedule-based trigger sub-type. - PHASE_SUB_TYPE_WEBHOOK: Webhook trigger sub-type. - PHASE_SUB_TYPE_API: API trigger sub-type. 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 organization_display_name: type: string description: |- The display name of the parent organization, surfaced output-only to avoid a second GetOrganization round-trip from clients that render the workspace's parent 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). Format: data:[][;encoding], Server-side max payload size: 10MB. Coexists with `workspace_icon` (preset id) + `workspace_icon_color`. If both `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 v1ListRunEventsResponse: type: object properties: run_events: type: array items: $ref: "#/components/schemas/v1RunEvent" description: |- The list of run events for the requested page. Events are returned in the order specified by the request's order_by field (default: chronological / oldest first). Each event contains either: - A run state update from the Jeeves orchestration service - An execution journal entry from the Jarvis execution engine next_page_token: type: string description: >- Pagination token for retrieving the next page of events. Include this token as the `page_token` in a subsequent ListRunEvents request to retrieve the next set of events. The token maintains cursor position and ensures consistent pagination even if new events are added to the run. When this field is empty or omitted: - This is the final page of results - All events for the run have been retrieved - No further pagination requests are needed The token is opaque. Do not attempt to parse, modify, or reuse tokens across different parent resources or request parameters. description: |- Response message for the ListRunEvents RPC. Contains a page of run events along with pagination information for retrieving additional events. Events are sorted by their occurrence time in the direction specified by the request's order_by field (default: ascending / oldest first). The response may contain fewer events than requested if: - The run has fewer remaining events than the page size - This is the final page of results - Response size limits are reached v1RunEvent: type: object properties: run_update: $ref: "#/components/schemas/v1RunUpdate" execution_journal: $ref: "#/components/schemas/v1ExecutionJournal" description: A single event that occurred during an automation run execution. v1ExecutionJournal: type: object properties: execution_id: type: string title: Unique identifier for the execution run_id: type: string title: "Optional: Run identifier, set if the execution is part of a run" event_time: type: string format: date-time title: When this journal entry was generated started: $ref: "#/components/schemas/v1ExecutionStarted" completed: $ref: "#/components/schemas/v1ExecutionCompleted" stopped: $ref: "#/components/schemas/v1ExecutionStopped" failed: $ref: "#/components/schemas/v1ExecutionFailed" node_started: $ref: "#/components/schemas/v1NodeStarted" node_executed: $ref: "#/components/schemas/v1NodeExecuted" node_skipped: $ref: "#/components/schemas/v1NodeSkipped" node_patched: $ref: "#/components/schemas/v1NodePatched" patched_node_started: $ref: "#/components/schemas/v1PatchedNodeStarted" patched_node_executed: $ref: "#/components/schemas/v1PatchedNodeExecuted" automation_id: type: string title: "Optional: Automation identifier, set if the execution is part of an automation" automation_phase_id: type: string title: "Optional: Automation phase identifier, set if the execution is part of an automation phase" code_hash: type: string title: "Optional: MD5 hash of the SPy code being executed" stage: $ref: "#/components/schemas/v1AutomationStage" workspace_id: type: string title: The workspace id for which the execution is requested organization_id: type: string title: The organization id for which the execution is requested extra_metadata: type: object additionalProperties: $ref: "#/components/schemas/commonV1Value" description: >- Optional extra metadata to be stored with the execution This will be used to pass the additional information that downstream services might require but there is no need to Jarvis to know about it. title: Journal event for an execution, capturing status and node-level events v1ExecutionCompleted: type: object properties: outputs: type: object additionalProperties: $ref: "#/components/schemas/commonV1Value" description: >- Map of named output values set by the set_output() builtin function during execution. Each entry is a name-value pair where the key is the output name (string) and the value is the output value set by calling set_output(name, value). This map will be empty if no set_output() calls were made during execution. return_value: $ref: "#/components/schemas/commonV1Value" description: >- ExecutionCompleted indicates that Jarvis has successfully completed the execution. The final result value is included in this message, representing the return value of the executed code. commonV1Value: type: object properties: null_value: type: string title: Represents the absence of a value (None/null/undefined) bool_value: type: boolean title: Boolean true/false value number: $ref: "#/components/schemas/v1Number" text: type: string title: UTF-8 encoded text string date: $ref: "#/components/schemas/typeDate" timeofday: $ref: "#/components/schemas/typeTimeOfDay" datetime: $ref: "#/components/schemas/typeDateTime" time_zone: $ref: "#/components/schemas/typeTimeZone" duration: type: string title: Signed duration representing a span of time list: $ref: "#/components/schemas/v1List" dictionary: $ref: "#/components/schemas/v1Dictionary" file: $ref: "#/components/schemas/v1FileValue" table: $ref: "#/components/schemas/v1TableValue" set: $ref: "#/components/schemas/v1Set" text_value: $ref: "#/components/schemas/v1TextValue" list_value: $ref: "#/components/schemas/commonv1ListValue" set_value: $ref: "#/components/schemas/v1SetValue" dictionary_value: $ref: "#/components/schemas/v1DictionaryValue" description: >- Represents a runtime value that can be produced by the Jarvis interpreter. This message provides a type-safe way to serialize and transmit values between the Jarvis interpreter and other services via gRPC. It supports all the basic data types that can be represented in the Jarvis language runtime. The oneof structure ensures that exactly one value type is set at a time, providing both type safety and efficient serialization. typeDateTime: type: object properties: year: type: integer format: int32 description: |- Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a datetime without a year. month: type: integer format: int32 description: Required. Month of year. Must be from 1 to 12. day: type: integer format: int32 description: >- Required. Day of month. Must be from 1 to 31 and valid for the year and month. hours: type: integer format: int32 description: >- Required. Hours of day in 24 hour format. Should be from 0 to 23. An API may choose to allow the value "24:00:00" for scenarios like business closing time. minutes: type: integer format: int32 description: Required. Minutes of hour of day. Must be from 0 to 59. seconds: type: integer format: int32 description: >- Required. Seconds of minutes of the time. Must normally be from 0 to 59. An API may allow the value 60 if it allows leap-seconds. nanos: type: integer format: int32 description: |- Required. Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999. utc_offset: type: string description: |- UTC offset. Must be whole seconds, between -18 hours and +18 hours. For example, a UTC offset of -4:00 would be represented as { seconds: -14400 }. time_zone: $ref: "#/components/schemas/typeTimeZone" description: >- Represents civil time (or occasionally physical time). This type can represent a civil time in one of a few possible ways: * When utc_offset is set and time_zone is unset: a civil time on a calendar day with a particular offset from UTC. * When time_zone is set and utc_offset is unset: a civil time on a calendar day in a particular time zone. * When neither time_zone nor utc_offset is set: a civil time on a calendar day in local time. The date is relative to the Proleptic Gregorian Calendar. If year is 0, the DateTime is considered not to have a specific year. month and day must have valid, non-zero values. This type may also be used to represent a physical time if all the date and time fields are set and either case of the `time_offset` oneof is set. Consider using `Timestamp` message for physical time instead. If your use case also would like to store the user's timezone, that can be done in another field. This type is more flexible than some applications may want. Make sure to document and validate your application's limitations. typeTimeZone: type: object properties: id: type: string description: IANA Time Zone Database time zone, e.g. "America/New_York". version: type: string description: Optional. IANA Time Zone Database version number, e.g. "2019a". description: |- Represents a time zone from the [IANA Time Zone Database](https://www.iana.org/time-zones). v1Number: type: object properties: lo: type: integer format: int64 description: Low 32 bits of the 96-bit mantissa. mid: type: integer format: int64 description: Middle 32 bits of the 96-bit mantissa. hi: type: integer format: int64 description: High 32 bits of the 96-bit mantissa. flags: type: integer format: int64 description: |- Flags word: - Bits 16–23: scale (0–28) - Bit 31: sign (0 = positive, 1 = negative) - Other bits must be zero. description: | A fixed-precision decimal number with up to 28 fractional digits. This message represents decimal numbers with exact precision, avoiding floating-point rounding errors. It's particularly useful for financial calculations, measurements, and any scenario where exact decimal representation is required. The value is calculated as: m / 10^e, where: - m is an unsigned 96-bit integer composed of (lo, mid, hi) - e is the scale (0–28) stored in flags bits 16–23 - sign is encoded in flags bit 31 (0 = positive, 1 = negative) Examples: - 123.45 would have m=12345, e=2 - -0.001 would have m=1, e=3, with sign bit set v1FileValue: type: object properties: remote: type: string title: Reference to a remote file via URL or file path inline: $ref: "#/components/schemas/v1File" description: |- Represents a file value that can be either stored inline or referenced remotely. This message provides flexibility for handling files in the Jarvis interpreter: - Small files can be embedded directly using the inline option - Large files can be referenced by URL/path using the remote option - The choice depends on file size, network constraints, and access patterns v1File: type: object properties: content: type: string format: byte title: The raw binary content of the file name: type: string title: The name of the file, including extension if applicable description: | Represents a file with its name and binary content. This message contains the complete file data including both metadata (filename) and the actual file content as raw bytes. It's used for embedding files directly within messages when the file size is manageable and immediate access is required. Examples: - Configuration files - Small text or binary files - Generated reports or documents - Temporary files created during execution typeTimeOfDay: type: object properties: hours: type: integer format: int32 description: >- Hours of day in 24 hour format. Should be from 0 to 23. An API may choose to allow the value "24:00:00" for scenarios like business closing time. minutes: type: integer format: int32 description: Minutes of hour of day. Must be from 0 to 59. seconds: type: integer format: int32 description: >- Seconds of minutes of the time. Must normally be from 0 to 59. An API may allow the value 60 if it allows leap-seconds. nanos: type: integer format: int32 description: Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999. description: >- Represents a time of day. The date and time zone are either not significant or are specified elsewhere. An API may choose to allow leap seconds. Related types are [google.type.Date][google.type.Date] and `google.protobuf.Timestamp`. v1TableValue: type: object properties: remote: type: string title: Reference to a remote table via URL or file path (feather-v2 format) inline: $ref: "#/components/schemas/v1Table" description: Represents a table value that can be either stored inline or referenced remotely. v1Table: type: object properties: data: type: string format: byte title: The table data serialized in feather-v2 format description: |- Represents a table with data in feather-v2 format. This message contains the complete table data serialized using the feather-v2 format, which provides efficient columnar storage and fast serialization/deserialization for tabular data. v1DictionaryValue: type: object properties: remote: type: string title: Reference to remote dictionary data via URL or file path inline: $ref: "#/components/schemas/v1Dictionary" description: |- Represents a dictionary value that can be either stored inline or referenced remotely. This message provides flexibility for handling large dictionaries: - Small dictionaries can be embedded directly using the inline option - Large dictionaries can be referenced by URL using the remote option v1Dictionary: type: object properties: entries: type: array items: $ref: "#/components/schemas/v1DictionaryEntry" title: The key-value pairs stored in this dictionary description: >- Represents a key-value mapping (similar to hash maps or dictionaries). This message stores associations between keys and values, where keys must be hashable types (null, bool, Number, string, Date, TimeOfDay, DateTime, TimeZone). Keys are unique within a dictionary - duplicate keys will overwrite previous values. The dictionary maintains insertion order for consistent iteration behavior. Examples: - {"name": "John", "age": 30} - string keys with mixed values - {1: "one", 2: "two"} - number keys with string values - {"nested": {"inner": "value"}} - nested dictionaries v1DictionaryEntry: type: object properties: key: $ref: "#/components/schemas/v1HashableValue" value: $ref: "#/components/schemas/commonV1Value" description: |- Represents a single key-value pair within a Dictionary. Both key and value can be any Value type, though keys should be hashable types for proper dictionary behavior. Non-hashable keys (like lists or dictionaries) may cause runtime errors. v1HashableValue: type: object properties: bool_value: type: boolean title: Boolean true/false value number: $ref: "#/components/schemas/v1Number" text: type: string title: UTF-8 encoded text string date: $ref: "#/components/schemas/typeDate" timeofday: $ref: "#/components/schemas/typeTimeOfDay" datetime: $ref: "#/components/schemas/typeDateTime" duration: type: string title: Signed duration representing a span of time text_value: $ref: "#/components/schemas/v1TextValue" description: |- Represents a hashable value that can be used as a dictionary key. This message contains only the hashable types from the Value message, corresponding to Python's hashable types. These types can be safely used as keys in maps and dictionaries. Hashable types include: bool, Number, string, Date, TimeOfDay, DateTime and Duration. typeDate: type: object properties: year: type: integer format: int32 description: >- Year of the date. Must be from 1 to 9999, or 0 to specify a date without a year. month: type: integer format: int32 description: >- Month of a year. Must be from 1 to 12, or 0 to specify a year without a month and day. day: type: integer format: int32 description: >- Day of a month. Must be from 1 to 31 and valid for the year and month, or 0 to specify a year by itself or a year and month where the day isn't significant. description: >- * A full date, with non-zero year, month, and day values * A month and day value, with a zero year, such as an anniversary * A year on its own, with zero month and day values * A year and month value, with a zero day, such as a credit card expiration date Related types are [google.type.TimeOfDay][google.type.TimeOfDay] and `google.protobuf.Timestamp`. title: >- Represents a whole or partial calendar date, such as a birthday. The time of day and time zone are either specified elsewhere or are insignificant. The date is relative to the Gregorian Calendar. This can represent one of the following: v1List: type: object properties: items: type: array items: $ref: "#/components/schemas/commonV1Value" title: The ordered sequence of values in this list description: >- Represents an ordered collection of values (similar to arrays or lists). This message can contain any number of Value elements in a specific order. Lists are mutable and can grow or shrink during runtime. Elements can be accessed by their zero-based index position. Examples: - [1, 2, 3] - list of numbers - ["hello", "world"] - list of strings - [true, 42, "mixed"] - list with mixed types - [[1, 2], [3, 4]] - nested lists v1Set: type: object properties: items: type: array items: $ref: "#/components/schemas/v1HashableValue" title: |- The unique elements stored in this set All elements must be hashable types description: >- Represents an unordered collection of unique values. This message stores a collection of unique elements, where duplicate values are automatically removed. Only hashable types can be stored in sets. Sets are useful for membership testing, removing duplicates, and mathematical set operations like union, intersection, and difference. The set does not maintain insertion order - elements may appear in any order during iteration. Examples: - {1, 2, 3} - set of numbers - {"apple", "banana", "cherry"} - set of strings - {true, false} - set of booleans - {1, "hello", true} - set with mixed hashable types v1AutomationStage: type: string enum: - AUTOMATION_STAGE_UNSPECIFIED - AUTOMATION_STAGE_DRAFT - AUTOMATION_STAGE_PUBLISHED default: AUTOMATION_STAGE_UNSPECIFIED description: >- AutomationStage represents the publication stage of an automation. This enum is shared across services that manage or execute automations. - AUTOMATION_STAGE_UNSPECIFIED: Automation stage is not specified. - AUTOMATION_STAGE_DRAFT: Automation is in draft stage and can be modified. - AUTOMATION_STAGE_PUBLISHED: Automation is published and immutable, ready for execution. v1ExecutionStarted: type: object description: ExecutionStarted indicates that Jarvis has started the execution. v1PatchedNodeExecuted: type: object properties: patch_location: $ref: "#/components/schemas/commonV1Location" node_location: $ref: "#/components/schemas/commonV1Location" inputs: type: object additionalProperties: $ref: "#/components/schemas/commonV1Value" description: |- The input variables & their values A variable is defined as an input if it was fetched from the memory while executing the node or one of its children. outputs: type: object additionalProperties: $ref: "#/components/schemas/commonV1Value" description: |- The output variables & their values A variable is defined as an output if it was written to the memory while executing the node or one of its children. If a variable was written multiple times, only the last written value is considered as the output. error: type: array items: $ref: "#/components/schemas/v1ExecutionError" description: |- The list of all the errors that occurred while executing the node or any of its children. node_id: type: string title: The id of the patched node for which execution is completed book_function_call: $ref: "#/components/schemas/v1BookFunctionCall" node_kind: type: string title: The kind/type of the patched node that was executed function_call_context: $ref: "#/components/schemas/v1FunctionCallContext" title: Event emitted after executing a node inside a patch, with I/O and errors v1BookFunctionCall: type: object properties: book_function: $ref: "#/components/schemas/v1BookFunction" inputs: type: object additionalProperties: $ref: "#/components/schemas/commonV1Value" title: The input variables and their values passed to the book function output: $ref: "#/components/schemas/commonV1Value" description: BookFunctionCall represents a call to an external book function with its inputs and outputs. v1BookFunction: type: object properties: connection_spy_identifier: type: string title: The connection name for the book instance in the spy code book_name: type: string title: The name of the target book containing the function function_name: type: string title: The name of the specific function to invoke within the book code_location: $ref: "#/components/schemas/commonV1Location" description: BookFunction represents a reference to an external book function. commonV1Location: type: object properties: start_byte: type: string format: int64 title: Starting Byte of the span, It will be zero-based end_byte: type: string format: int64 title: Ending Byte(exclusive) of the span, It will be zero-based start_position: $ref: "#/components/schemas/v1Position" end_position: $ref: "#/components/schemas/v1Position" description: >- Location represents a generic span within some underlying content. It specifies the starting byte offset and the ending byte offset (exclusive) of the span. This can be used for pointing to regions in files, buffers, logs, messages, or any other byte-addressable resource. v1ExecutionError: type: object properties: id: type: string title: Unique identifier for the error description: type: string title: Human-readable description of what went wrong context: $ref: "#/components/schemas/v1Context" extra: type: object additionalProperties: type: string title: Extra information about the error code: type: string title: >- The code where the error was raised (includes patches) If the error was raised in a patch, the code reflects the patched code and the error location is relative to the patched code instead of the original code Note: this field does not include previous patches that executed successfully typed_extra: type: object additionalProperties: $ref: "#/components/schemas/commonV1Value" title: Extra information about the error, as typed values that may be offloaded description: ExecutionError represents an error that occurred during execution. v1Context: type: object properties: code_location: $ref: "#/components/schemas/commonV1Location" node_id: type: string title: The id of node connections: type: object additionalProperties: $ref: "#/components/schemas/v1BookConnection" description: |- Book connections active at the time of failure (connection name → connection details). Allows consumers to know which connections were available when the error occurred, which is useful for re-submitting a resume with the correct connection IDs. runtime_values: type: object additionalProperties: $ref: "#/components/schemas/commonV1Value" description: |- Runtime values of the variables used by the sentence that failed (variable name → value). config: type: object additionalProperties: $ref: "#/components/schemas/commonV1Value" description: |- Read-only config values active at the time of failure (config name → value). Mirrors `connections`: lets consumers see the config the SPy code read via kognitos.config. when re-submitting a resume. description: |- Context provides additional information about the execution environment, such as stack traces for debugging purposes. v1NodeExecuted: type: object properties: code_location: $ref: "#/components/schemas/commonV1Location" inputs: type: object additionalProperties: $ref: "#/components/schemas/commonV1Value" description: |- The input variables & their values A variable is defined as an input if it was fetched from the memory while executing the node or one of its children. outputs: type: object additionalProperties: $ref: "#/components/schemas/commonV1Value" description: |- The output variables & their values A variable is defined as an output if it was written to the memory while executing the node or one of its children. If a variable was written multiple times, only the last written value is considered as the output. error: type: array items: $ref: "#/components/schemas/v1ExecutionError" description: |- The list of all the errors that occurred while executing the node or any of its children. node_id: type: string title: The id of the node that got executed book_function_call: $ref: "#/components/schemas/v1BookFunctionCall" node_kind: type: string title: The kind/type of the node that was executed function_call_context: $ref: "#/components/schemas/v1FunctionCallContext" title: Event emitted after Jarvis finishes executing an AST node, with I/O and errors v1NodeStarted: type: object properties: code_location: $ref: "#/components/schemas/commonV1Location" node_id: type: string title: The id of the node that was started node_kind: type: string title: The kind/type of the node that was started title: Event emitted when Jarvis begins executing an AST node v1PatchedNodeStarted: type: object properties: patch_location: $ref: "#/components/schemas/commonV1Location" node_location: $ref: "#/components/schemas/commonV1Location" node_id: type: string title: The id of the patched node for which execution is starting node_kind: type: string title: The kind/type of the patched node that is being started title: Event emitted when Jarvis starts executing a node inside a patch v1ExecutionFailed: type: object properties: error: $ref: "#/components/schemas/v1ExecutionError" description: |- ExecutionFailed indicates that the execution encountered an error and could not complete successfully. v1NodePatched: type: object properties: code_location: $ref: "#/components/schemas/commonV1Location" code_patch: type: string title: The patch SPy code that was applied inputs_patch: type: object additionalProperties: $ref: "#/components/schemas/commonV1Value" title: The execution inputs that were patched connections: type: object additionalProperties: $ref: "#/components/schemas/v1BookConnection" title: |- The book connections that were patched The key is the name of the connection used in the SPy code The value contains the connection details node_id: type: string title: The id of the node node_kind: type: string title: The kind/type of the node that was patched title: Event emitted when a patch is applied to an AST node v1BookConnection: type: object properties: connection_id: type: string description: Unique identifier for this connection resource. endpoint: type: string description: Endpoint for the connection. description: >- BookConnection is a resource representing a connection to a book instance. A connection has a unique identifier and an endpoint. v1ExecutionStopped: type: object properties: user_stopped: $ref: "#/components/schemas/v1UserStopped" waiting_on_book: $ref: "#/components/schemas/v1WaitingOnBook" waiting_on_timer: $ref: "#/components/schemas/v1WaitingOnTimer" program_stopped: $ref: "#/components/schemas/v1ProgramStopped" description: >- ExecutionStopped indicates that the execution was stopped before completion due to a specific reason. v1ProgramStopped: type: object properties: reason: type: string description: The reason the program was stopped. description: ProgramStopped indicates that the execution was stopped by the program. v1UserStopped: type: object description: UserStopped indicates that the execution was stopped by a user. v1WaitingOnTimer: type: object properties: duration: type: string description: The duration of the timer. description: |- WaitingOnTimer indicates that the execution is stopped because its waiting for a timer to fire. The run manager is expected to resume the execution when the timer fires. v1WaitingOnBook: type: object description: >- WaitingOnBook indicates that the execution is stopped because its waiting on an async book procedure to complete. The run manager is expected to resume the execution when the book procedure completes. v1NodeSkipped: type: object properties: code_location: $ref: "#/components/schemas/commonV1Location" node_id: type: string title: The id of the node that was skipped node_kind: type: string title: The kind/type of the node that was skipped title: Event emitted when Jarvis skips executing an AST node v1RunUpdate: type: object properties: run: $ref: "#/components/schemas/v1Run" description: RunUpdate represents a single update to a run's state. v1Run: type: object properties: name: type: string title: >- The name of the run. Format: organizations/{organization}/workspaces/{workspace}/automations/{automation}/runs/{run} executable_steps: $ref: "#/components/schemas/v1ExecutableSteps" create_time: type: string format: date-time description: |- The timestamp when this run was created. Set automatically when the run is first submitted to the system. readOnly: true state: $ref: "#/components/schemas/v1RunState" update_time: type: string format: date-time description: |- The timestamp when this run was updated. Set automatically when the run is updated. readOnly: true previous_run: type: string title: >- The name of the previous run in the chain, if applicable. Execution details of the previous run may be used to avoid re-computation. Format: organizations/{organization}/workspaces/{workspace}/automations/{automation}/runs/{run} stage: $ref: "#/components/schemas/v1AutomationStage" stage_version: type: string description: The version of the automation stage at the time this run was created. invocation_details: $ref: "#/components/schemas/v1InvocationDetails" user_inputs: type: object additionalProperties: $ref: "#/components/schemas/commonV1Value" description: The user inputs provided to the run during pre phase and will be available for the UI to display the user inputs. root_run: type: string title: |- The first run in this run's replay lineage. A run created fresh is its own root; a run created by ReplayRun shares its source run's root. Lets a whole replay lineage be fetched in one query (ListRuns filtered by root_run), and top-level runs be listed by filtering for an empty previous_run. Format: organizations/{organization}/workspaces/{workspace}/automations/{automation}/runs/{run} readOnly: true disable_exception_handling: type: boolean description: |- Whether to disable exception creation and handling when this run encounters guidance and enters the Awaiting Guidance state. Applies only to draft-stage runs. Published-stage runs always use standard Astral exception handling. enable_astral_on_rain: type: boolean description: |- Whether exception handling should be performed by the Astral agent deployed on the Rain agent framework. active_step_index: type: integer format: int32 description: |- The zero-based index of the step currently executing within executable_steps. Absent when executable_steps is empty (single-step runs without a pre-phase). readOnly: true archived_time: type: string format: date-time description: |- The timestamp when this run was archived, if it has been archived. When set, the run cannot be mutated (pause, resume, skip, patch, retry). The state field continues to reflect the real terminal execution state. readOnly: true content_coverage: $ref: "#/components/schemas/v1RunContentCoverage" description: >- Run represents a single execution instance of code in the Jeeves platform. Contains the executable code, metadata, and current execution state. required: - stage - stage_version v1InvocationDetails: type: object properties: trigger_id: type: string description: The ID of the trigger that initiated this run, if applicable. user_id: type: string description: The ID of the user that initiated this run, if applicable. invocation_source: $ref: "#/components/schemas/v1InvocationSource" description: InvocationDetails contains additional information about the entity that initiated a run. v1InvocationSource: type: string enum: - INVOCATION_SOURCE_UNSPECIFIED - INVOCATION_SOURCE_MANUAL - INVOCATION_SOURCE_TRIGGER - INVOCATION_SOURCE_SCHEDULE - INVOCATION_SOURCE_PAT - INVOCATION_SOURCE_TEST default: INVOCATION_SOURCE_UNSPECIFIED description: |- InvocationSource identifies the entity responsible for creating a run. - INVOCATION_SOURCE_UNSPECIFIED: Unspecified invocation source. - INVOCATION_SOURCE_MANUAL: Run was manually initiated by a user. - INVOCATION_SOURCE_TRIGGER: Run was triggered by an event or trigger. - INVOCATION_SOURCE_SCHEDULE: Run was initiated by a schedule. - INVOCATION_SOURCE_PAT: Run was initiated via a Personal Access Token (PAT). - INVOCATION_SOURCE_TEST: Run was initiated by Quill agent for testing draft automations. v1RunState: type: object properties: pending: $ref: "#/components/schemas/v1PendingRunState" executing: $ref: "#/components/schemas/v1ExecutingRunState" stopping: $ref: "#/components/schemas/v1StoppingRunState" stopped: $ref: "#/components/schemas/v1StoppedRunState" awaiting_guidance: $ref: "#/components/schemas/v1AwaitingGuidanceRunState" completed: $ref: "#/components/schemas/v1CompletedRunState" failed: $ref: "#/components/schemas/v1FailedRunState" update_time: type: string format: date-time description: The timestamp when the run transitioned to this state. readOnly: true archived: $ref: "#/components/schemas/v1ArchivedRunState" awaiting_answer: $ref: "#/components/schemas/v1AwaitingAnswerRunState" description: |- RunState represents the overall lifecycle state of a run. Tracks the run from initial submission through completion or failure. v1AwaitingGuidanceRunState: type: object properties: exception: type: string title: ID of the exception (from guidance center) readOnly: true description: type: string description: Description of the exception that occured. readOnly: true location: $ref: "#/components/schemas/commonV1Location" rain_thread_id: type: string description: |- The Rain thread ID for this exception on the Astral-on-Rain path. Each exception gets its own Rain thread so clients can subscribe to just this exception's events. Empty on the local path or when Rain is disabled. readOnly: true description: |- Run is waiting for external guidance or user input. Requires manual intervention or external decision to proceed. v1FailedRunState: type: object properties: id: type: string description: The unique identifier of the error that caused the run to fail. readOnly: true description: type: string description: The description of the error. readOnly: true location: $ref: "#/components/schemas/commonV1Location" description: |- Run has failed due to an error. Execution stopped due to an unrecoverable error condition. v1StoppedRunState: type: object properties: reason: type: string description: The reason provided by the user for stopping the run. readOnly: true description: |- Run has been stopped and can be resumed later. Execution is temporarily stopped but can continue from current state. v1StoppingRunState: type: object properties: reason: type: string description: The reason provided by the user for stopping the run. readOnly: true description: |- Run is in the process of being stopped. Execution is stopping gracefully and will transition to STOPPED state. v1CompletedRunState: type: object properties: outputs: type: object additionalProperties: $ref: "#/components/schemas/commonV1Value" description: The outputs of the run. readOnly: true description: |- Run has completed successfully. All code has been executed and results are available. v1PendingRunState: type: object description: |- Run has been submitted and is waiting to start execution. The run is queued and will begin when resources become available. v1ExecutingRunState: type: object description: |- Run is currently being executed. Code is actively running and making progress. v1ExecutableSteps: type: object properties: inputs: type: object additionalProperties: $ref: "#/components/schemas/commonV1Value" description: |- Input parameters for the execution, provided as name-value pairs. These variables will be available to the code during execution. executables: type: array items: $ref: "#/components/schemas/v1ExecutableStep" description: The source code to be executed, written in SPy (Simplified Python) language. description: >- ExecutableSteps represents a sequence of steps of execution of a run. Each step is a separate computable unit with its own code, book connections and optional inputs. The first step may optionally have an input provided to it when the run is invoked. The output of each step becomes the input of the next step and the output of the last step becomes the output of the run. required: - executables v1ExecutableStep: type: object properties: code: type: string description: >- The source code to be executed, written in SPy (Simplified Python) language. This is the main logic that will be interpreted and run by the execution engine. book_connections: type: object additionalProperties: $ref: "#/components/schemas/v1BookConnection" description: |- Book connections required by this executable. Maps connection names to their specific ID and endpoints. phase_type: $ref: "#/components/schemas/v1AutomationPhaseType" collections: type: object additionalProperties: $ref: "#/components/schemas/v1CollectionRef" description: |- Collections referenced by this step. Maps each collection slug to its reference. index: type: integer format: int32 description: Zero-based position of this step within executable_steps. readOnly: true config: type: object additionalProperties: $ref: "#/components/schemas/commonV1Value" description: |- Business-tunable config for this step, keyed by config name and resolved to plain values. Read in SPy as kognitos.config.. description: >- ExecutableStep represents a piece of code that can be executed in the Jeeves platform. Contains the source code, input parameters, and external dependencies needed for execution. required: - code - phase_type v1AutomationPhaseType: type: string enum: - AUTOMATION_PHASE_TYPE_UNSPECIFIED - AUTOMATION_PHASE_TYPE_PRE - AUTOMATION_PHASE_TYPE_MAIN - AUTOMATION_PHASE_TYPE_POST default: AUTOMATION_PHASE_TYPE_UNSPECIFIED description: |- PhaseType defines the type of phase for an automation trigger. - AUTOMATION_PHASE_TYPE_UNSPECIFIED: Unspecified phase type. - AUTOMATION_PHASE_TYPE_PRE: Pre-processing phase. - AUTOMATION_PHASE_TYPE_MAIN: Main processing phase. - AUTOMATION_PHASE_TYPE_POST: Post-processing phase. v2Expression: type: object properties: binary_expression: $ref: "#/components/schemas/v2BinaryExpression" unary_expression: $ref: "#/components/schemas/v2UnaryExpression" value_expression: $ref: "#/components/schemas/bdkV2Value" noun_phrases_expression: $ref: "#/components/schemas/v2NounPhrases" v2UnaryExpression: type: object properties: operator: $ref: "#/components/schemas/v2UnaryOperator" inner: $ref: "#/components/schemas/v2Expression" v2UnaryOperator: type: string enum: - UnaryOperatorNot - UnaryOperatorExists default: UnaryOperatorNot v2BinaryExpression: type: object properties: operator: $ref: "#/components/schemas/v2BinaryOperator" left: $ref: "#/components/schemas/v2Expression" right: $ref: "#/components/schemas/v2Expression" v2BinaryOperator: type: string enum: - BinaryOperatorAnd - BinaryOperatorOr - BinaryOperatorEquals - BinaryOperatorNotEquals - BinaryOperatorIn - BinaryOperatorHas - BinaryOperatorLessThan - BinaryOperatorGreaterThan - BinaryOperatorLessThanOrEqual - BinaryOperatorGreaterThanOrEqual default: BinaryOperatorAnd bdkV2Value: type: object properties: null_value: type: string conceptual_value: $ref: "#/components/schemas/v2NounPhrase" text_value: type: string title: "deprecated: use offloadable_text_value (15) for new code" number_value: type: number format: double boolean_value: type: boolean datetime_value: type: string format: date-time date_value: $ref: "#/components/schemas/v2Date" time_value: $ref: "#/components/schemas/v2Time" file_value: $ref: "#/components/schemas/v2FileValue" dictionary_value: $ref: "#/components/schemas/v2DictionaryValue" list_value: $ref: "#/components/schemas/bdkV2ListValue" opaque_value: $ref: "#/components/schemas/v2OpaqueValue" table_value: $ref: "#/components/schemas/v2TableValue" sensitive_value: $ref: "#/components/schemas/v2SensitiveValue" offloadable_text_value: $ref: "#/components/schemas/v2OffloadableTextValue" offloadable_dictionary_value: $ref: "#/components/schemas/v2OffloadableDictionaryValue" offloadable_list_value: $ref: "#/components/schemas/v2OffloadableListValue" title: A union of all possible values v2DictionaryValue: type: object properties: fields: type: array items: $ref: "#/components/schemas/v2DictionaryValueField" title: All the fields alongside their values in the dictionary is_a: type: array items: $ref: "#/components/schemas/v2NounPhrase" title: Is a replationships for the dictionary title: Value to be used when the type is dictionary v2DictionaryValueField: type: object properties: key: type: string value: $ref: "#/components/schemas/bdkV2Value" title: Each key-value pair inside a dictionary v2NounPhrase: type: object properties: modifiers: type: array items: type: string title: Optional adjectives attached to the noun head: type: string title: Noun of the phrase bdkV2ListValue: type: object properties: values: type: array items: $ref: "#/components/schemas/bdkV2Value" title: All the values inside the list title: A collection of values v2TableValue: type: object properties: remote: type: string inline: $ref: "#/components/schemas/v2Table" title: >- A table that is represented remote as an URL to a file that is Feather-formatted or inline via the Table message v2Table: type: object properties: columns: type: array items: $ref: "#/components/schemas/v2Column" description: >- A table is a column-oriented structure. All the values inside each column must be of equal length. v2Column: type: object properties: values: type: array items: $ref: "#/components/schemas/bdkV2Value" name: type: string v2FileValue: type: object properties: remote: type: string inline: $ref: "#/components/schemas/v2File" title: A file value represents a file that can be either inline or remote v2File: type: object properties: file_name: type: string title: The name of the file content: type: string format: byte title: Content of the file as a byte stream v2Date: type: object properties: year: type: integer format: int32 title: Year of the date month: type: integer format: int32 title: Month of a year day: type: integer format: int32 title: Day of a month v2OffloadableTextValue: type: object properties: remote: type: string inline: type: string title: A text value that can be either inline or stored remotely v2SensitiveValue: type: object properties: value: $ref: "#/components/schemas/bdkV2Value" title: A sensitive value is any value marked as sensitive (to prevent exposure) v2OpaqueValue: type: object properties: content: type: string format: byte title: Content of the opaque value is_a: type: array items: $ref: "#/components/schemas/v2NounPhrase" title: Is a replationships for the opaque v2OffloadableListValue: type: object properties: remote: type: string inline: $ref: "#/components/schemas/bdkV2ListValue" title: A list value that can be either inline or stored remotely v2OffloadableDictionaryValue: type: object properties: remote: type: string inline: $ref: "#/components/schemas/v2DictionaryValue" title: A dictionary value that can be either inline or stored remotely v2Time: type: object properties: hours: type: integer format: int32 title: Hours of day minutes: type: integer format: int32 title: Minutes of hour of day seconds: type: integer format: int32 title: Seconds of minutes of the time nanos: type: integer format: int32 title: Fractions of seconds in nanoseconds v2NounPhrases: type: object properties: noun_phrases: type: array items: $ref: "#/components/schemas/v2NounPhrase" v2BookConnectionResponse: type: object properties: book_connection_descriptor: $ref: "#/components/schemas/v2BookConnectionDescriptor" authorize_url: $ref: "#/components/schemas/v2BookConnectionOAuthURLResponse" title: The response to an add/update book connection request v2BookConnectionDescriptor: type: object properties: book_name: type: string title: The name of the book book_version: type: string title: The version of the book connection_id: type: string title: The connection id of the book connection_name: type: string title: The connection name authentication: $ref: "#/components/schemas/v2Authentication" config: type: array items: $ref: "#/components/schemas/v2ConceptValue" title: "Input config concepts. Note: replaced by config_map" labels: type: array items: $ref: "#/components/schemas/bdkV2Label" title: Labels associated with the connection status: $ref: "#/components/schemas/v2BookConnectionStatus" endpoint: type: string title: The endpoint of the connection discovered: type: array items: type: string title: The list of things that have been discovered config_map: type: object additionalProperties: $ref: "#/components/schemas/bdkV2Value" title: Configured values associated_remote_connection_id: type: string title: The id of the associated remote connection shared: type: boolean title: True when this connection is shared with every workspace, and so cannot be modified credentials_id: type: string title: Managed secret store name backing this connection's credential auto_upgrade: type: boolean description: |- True when the controller may automatically upgrade this connection to newer non-breaking (same major) versions of the book. Defaults to true. bdkV2Label: type: object properties: key: type: string title: The key of the key-value pair value: type: string title: The value of the key-value pair v2ConceptValue: type: object properties: noun_phrases: $ref: "#/components/schemas/v2NounPhrases" value: $ref: "#/components/schemas/bdkV2Value" v2Authentication: type: object properties: authentication_id: type: string title: Identifier of the authentication method to be used for testing the connection authentication_credentials: type: array items: $ref: "#/components/schemas/v2CredentialValue" title: Credentials v2CredentialValue: type: object properties: id: type: string title: Id of the credential value: $ref: "#/components/schemas/bdkV2Value" v2BookConnectionStatus: type: object properties: state: $ref: "#/components/schemas/v2BookConnectionState" state_category: $ref: "#/components/schemas/v2BookConnectionStateCategory" reason: type: string title: Human-readable message providing additional details about the current state last_updated: type: string title: RFC 3339 timestamp of when the status was last updated conditions: type: array items: $ref: "#/components/schemas/v2BookConnectionCondition" title: List of conditions that apply to the BookConnection title: Status information for a BookConnection v2BookConnectionStateCategory: type: string enum: - BOOK_CONNECTION_STATE_CATEGORY_WARNING - BOOK_CONNECTION_STATE_CATEGORY_READY - BOOK_CONNECTION_STATE_CATEGORY_FAILED default: BOOK_CONNECTION_STATE_CATEGORY_WARNING title: The category/level of the connection state v2BookConnectionState: type: string enum: - BOOK_CONNECTION_STATE_PENDING - BOOK_CONNECTION_STATE_READY - BOOK_CONNECTION_STATE_FAILED - BOOK_CONNECTION_STATE_CONDITIONS_NOT_MET - BOOK_CONNECTION_STATE_UNKNOWN - BOOK_CONNECTION_STATE_INACTIVE default: BOOK_CONNECTION_STATE_PENDING title: Possible phases for a BookConnection (Pending, ConditionsNotMet, Ready, Failed, Unknown, Inactive) description: "- BOOK_CONNECTION_STATE_INACTIVE: Scaled to zero due to inactivity; kept for on-demand reactivation." v2BookConnectionCondition: type: object properties: type: $ref: "#/components/schemas/v2BookConnectionConditionType" status: $ref: "#/components/schemas/v2BookConnectionConditionStatus" last_transition_time: type: string title: RFC 3339 timestamp of when this condition was last updated reason: type: string title: Brief reason explaining the condition reason_code: $ref: "#/components/schemas/v2BookConnectionConditionReasonCode" title: Condition information for BookConnection v2BookConnectionConditionStatus: type: string enum: - BOOK_CONNECTION_CONDITION_STATUS_TRUE - BOOK_CONNECTION_CONDITION_STATUS_FALSE - BOOK_CONNECTION_CONDITION_STATUS_UNKNOWN - BOOK_CONNECTION_CONDITION_STATUS_PENDING default: BOOK_CONNECTION_CONDITION_STATUS_TRUE description: >- Possible Values: - True: All good - False: An error occurred - Unknown: Condition not applicable/relevant - Pending: Underlying process (upon which the condition depends) still ongoing title: Status values for conditions v2BookConnectionConditionReasonCode: type: string enum: - BOOK_CONNECTION_CONDITION_REASON_CODE_BOOK_LOOKUP_FAILED - BOOK_CONNECTION_CONDITION_REASON_CODE_BOOK_NOT_FOUND - BOOK_CONNECTION_CONDITION_REASON_CODE_BOOK_MISSING_IMAGE - BOOK_CONNECTION_CONDITION_REASON_CODE_BOOK_RUNTIME_VERSION_OUTDATED - BOOK_CONNECTION_CONDITION_REASON_CODE_AUTHENTICATION_ID_NOT_FOUND - BOOK_CONNECTION_CONDITION_REASON_CODE_MISSING_CREDENTIAL - BOOK_CONNECTION_CONDITION_REASON_CODE_WRONG_CREDENTIAL_TYPE - BOOK_CONNECTION_CONDITION_REASON_CODE_SECRET_NOT_FOUND - BOOK_CONNECTION_CONDITION_REASON_CODE_SECRET_MISSING_KEY - BOOK_CONNECTION_CONDITION_REASON_CODE_AUTHENTICATION_REQUIRED_MISSING - BOOK_CONNECTION_CONDITION_REASON_CODE_AUTHENTICATION_TEST_FAILED - BOOK_CONNECTION_CONDITION_REASON_CODE_TOKEN_REFRESH_FAILED - BOOK_CONNECTION_CONDITION_REASON_CODE_CONFIGURATION_UNKNOWN_KEY - BOOK_CONNECTION_CONDITION_REASON_CODE_CONFIGURATION_WRONG_TYPE - BOOK_CONNECTION_CONDITION_REASON_CODE_REPLICA_COUNT_IS_ZERO - BOOK_CONNECTION_CONDITION_REASON_CODE_NEW_DEPLOYMENT_ROLLED_OUT - BOOK_CONNECTION_CONDITION_REASON_CODE_DISCOVER_IN_PROGRESS - BOOK_CONNECTION_CONDITION_REASON_CODE_DISCOVER_FAILED default: BOOK_CONNECTION_CONDITION_REASON_CODE_BOOK_LOOKUP_FAILED description: >- - BOOK_CONNECTION_CONDITION_REASON_CODE_BOOK_LOOKUP_FAILED: Book related - BOOK_CONNECTION_CONDITION_REASON_CODE_AUTHENTICATION_ID_NOT_FOUND: Authentication related - BOOK_CONNECTION_CONDITION_REASON_CODE_CONFIGURATION_UNKNOWN_KEY: Configuration related - BOOK_CONNECTION_CONDITION_REASON_CODE_REPLICA_COUNT_IS_ZERO: Connection related - BOOK_CONNECTION_CONDITION_REASON_CODE_DISCOVER_IN_PROGRESS: Discover related title: Machine-readable reason codes for condition transitions v2BookConnectionConditionType: type: string enum: - BOOK_CONNECTION_CONDITION_TYPE_BOOK_VALID - BOOK_CONNECTION_CONDITION_TYPE_AUTHENTICATION_VALID - BOOK_CONNECTION_CONDITION_TYPE_CONFIGURATION_VALID - BOOK_CONNECTION_CONDITION_TYPE_DEPLOYMENT_READY - BOOK_CONNECTION_CONDITION_TYPE_CREDENTIALS_VALID - BOOK_CONNECTION_CONDITION_TYPE_DISCOVER_READY - BOOK_CONNECTION_CONDITION_TYPE_TRIGGER_INSTANCES_READY - BOOK_CONNECTION_CONDITION_TYPE_COMPATIBLE_RUNTIME_VERSION - BOOK_CONNECTION_CONDITION_TYPE_POLL_INSTANCES_READY default: BOOK_CONNECTION_CONDITION_TYPE_BOOK_VALID description: |- Represents the various condition types that can be associated with a BookConnection. Conditions are categorized into two groups: 1. [Static Conditions] These conditions are determined solely by the BookConnection's data structure and configuration, and they can be validated without external dependencies or runtime state: - BOOK_VALID - AUTHENTICATION_VALID - CONFIGURATION_VALID 2. [Dynamic Conditions] These conditions depend on external factors and runtime state that can change independently of the BookConnection spec. They require active monitoring and periodic re-evaluation: - DEPLOYMENT_READY - CREDENTIALS_VALID - DISCOVER_READY - TRIGGER_INSTANCES_READY - COMPATIBLE_RUNTIME_VERSION - POLL_INSTANCES_READY - BOOK_CONNECTION_CONDITION_TYPE_BOOK_VALID: Static - BOOK_CONNECTION_CONDITION_TYPE_DEPLOYMENT_READY: Dynamic v2BookConnectionOAuthURLResponse: type: object properties: url: type: string title: |- The URL to kick off the OAuth flow. It contains: - The authorize endpoint - The state - The scope - The redirect uri v1ListAutomationsResponse: type: object properties: automations: type: array items: $ref: "#/components/schemas/v1Automation" description: |- The list of automations for the current page. May be empty if no automations match the request criteria. next_page_token: type: string description: |- A token that can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no subsequent pages. description: ListAutomationsResponse returns a page of automations and pagination information. v1Automation: type: object properties: name: type: string title: The automation name (e.g. 'automations/{automation}') display_name: type: string description: >- Human-readable name of the automation for identification and display. Must be unique within the user's namespace. english_code: type: string description: >- User-facing English description code that explains what the automation does. This is a human-readable representation of the automation's purpose and logic. code: type: string description: >- SPy (Subset-of Python) executable code that defines the automation logic. This code is executed when the automation is invoked with inputs. artifacts: type: object additionalProperties: type: string format: byte description: >- Additional artifacts associated with the automation (e.g., data files, configurations). Keys are artifact names, values are the binary content of the artifacts. These artifacts are available to the automation during execution. create_time: type: string format: date-time description: |- Timestamp when the automation was originally created. This value never changes after creation. readOnly: true version: type: string title: >- Semantic version of this specific version of the automation (format: major.minor). Incremented each time the automation is updated or published. Examples: "0.1", "1.0", "1.1", "2.0" readOnly: true connections: type: object additionalProperties: $ref: "#/components/schemas/v1BookConnection" description: >- Book connections required by this automation for execution. Maps connection names to their metadata. These connections are resolved and made available during automation execution. update_time: type: string format: date-time description: >- Timestamp when the automation was last updated. Updated whenever the automation metadata, code, or dependencies change. readOnly: true update_user_id: type: string description: The ID of the user who last updated this automation. readOnly: true delete_time: type: string format: date-time description: Timestamp when the automation was deleted. readOnly: true purge_time: type: string format: date-time description: Timestamp when the automation will be purged. readOnly: true input_specs: type: array items: $ref: "#/components/schemas/v1AutomationInputSpec" description: >- List of input specifications that define the parameters this automation accepts. These specifications describe the expected inputs when the automation is executed. description: type: string description: Provides additional context and documentation about the automation's purpose and behavior. latest_published_version: type: string title: >- Semantic version of the latest published version of the automation (format: major.minor). It will be null in case of no published version. Examples: "0.1", "1.0", "2.0" readOnly: true author_id: type: string description: The ID of the user who created this automation. readOnly: true code_mapping: $ref: "#/components/schemas/v1CodeMapping" restore_time: type: string format: date-time description: |- Timestamp when the automation was restored from a previous version. Only populated if the automation has been restored. readOnly: true restore_version: type: string description: >- The version string this automation was restored from (e.g., "1.0", "2.1"). Only populated if the automation has been restored. readOnly: true restore_user_id: type: string description: |- The ID of the user who restored this automation. Only populated if the automation has been restored. readOnly: true publish_time: type: string format: date-time description: |- Timestamp when the automation was last published. Only populated if the automation has been published. readOnly: true publish_user_id: type: string description: |- The ID of the user who last published this automation. Only populated if the automation has been published. readOnly: true activation_state: $ref: "#/components/schemas/v1AutomationActivationState" default_inputs: type: object additionalProperties: $ref: "#/components/schemas/commonV1Value" description: >- Default input values for this automation. Keys are input parameter names (matching AutomationInputSpec.name), values are the default values to use when inputs are not explicitly provided. These are used to pre-populate inputs for manual runs and fill missing inputs for trigger-based invocations. readOnly: true marked_outputs: type: array items: type: string description: |- List of output keys that have been marked by the user. These keys identify specific outputs from the automation execution. code_manifest: $ref: "#/components/schemas/v1CodeManifest" collections: type: object additionalProperties: $ref: "#/components/schemas/v1CollectionRef" description: |- Collections required by this automation, resolved to concrete references. Maps each collection slug to its CollectionRef (mirrors connections). config: type: object additionalProperties: $ref: "#/components/schemas/v1ConfigValue" description: |- Business-tunable configuration values for this automation, keyed by config name. Each ConfigValue holds the value plus a human-readable editor label. Set at build time, edited by the user to tune behavior, read in SPy as kognitos.config.. source_map: $ref: "#/components/schemas/v1SourceMap" code_length: type: integer format: int32 description: The length in characters of the SPy (Subset-of-Python) code. readOnly: true kind: $ref: "#/components/schemas/v1AutomationKind" labels: type: array items: type: string description: |- User-defined labels on the automation, e.g. "finance", "AP". Labels belong to the automation, not to a version: changing them does not create a new version. Ordered case-insensitively. Managed via SetAutomationLabels. readOnly: true description: >- Automation represents a unit of executable code with associated metadata and dependencies. Automations can be in DRAFT or PUBLISHED state, where drafts can be modified and published automations are immutable and executable. Automation IDs are unique nano ID strings (21 characters, URL-safe: A-Za-z0-9_-). required: - display_name v1AutomationInputSpec: type: object properties: name: type: string description: The name of the input parameter. type: $ref: "#/components/schemas/v1ValueType" description: AutomationInputSpec defines the specification for an input parameter of an automation. required: - name v1ValueType: type: object properties: scalar_type: $ref: "#/components/schemas/v1ValueScalarType" optional_type: $ref: "#/components/schemas/v1ValueOptionalType" list_type: $ref: "#/components/schemas/v1ValueListType" dictionary_type: $ref: "#/components/schemas/v1ValueDictionaryType" table_type: $ref: "#/components/schemas/v1ValueTableType" opaque_type: $ref: "#/components/schemas/v1ValueOpaqueType" any_type: $ref: "#/components/schemas/v1ValueAnyType" union_type: $ref: "#/components/schemas/v1ValueUnionType" sensitive_type: $ref: "#/components/schemas/v1ValueSensitiveType" enum_type: $ref: "#/components/schemas/v1ValueEnumType" generic_dictionary_type: $ref: "#/components/schemas/v1ValueGenericDictionaryType" none_type: $ref: "#/components/schemas/v1ValueNoneType" title: Represents a complete value type definition using a discriminated union v1ValueOpaqueType: type: object properties: is_a: type: string title: Semantic classification of what this opaque type represents description: type: string title: Optional human-readable description of this opaque type title: Represents an opaque value type with semantic meaning but unknown internal structure v1ValueListType: type: object properties: inner: $ref: "#/components/schemas/v1ValueType" title: Represents a list/array value type containing elements of a specific type v1ValueTableType: type: object properties: is_a: type: string title: Semantic classification of what this table represents columns: type: array items: $ref: "#/components/schemas/v1ValueTableTypeColumn" title: The columns that make up this table description: type: string title: Optional human-readable description of this table type title: Represents a table value type with structured columns v1ValueTableTypeColumn: type: object properties: key: type: string title: The name/key of this column value: $ref: "#/components/schemas/v1ValueType" description: type: string title: Optional human-readable description of this column title: Represents a single column within a table value type v1ValueSensitiveType: type: object properties: inner: $ref: "#/components/schemas/v1ValueType" title: Represents a value type that contains sensitive information v1ValueDictionaryType: type: object properties: is_a: type: string title: Semantic classification of what this dictionary represents fields: type: array items: $ref: "#/components/schemas/v1ValueDictionaryTypeField" title: The named fields contained in this dictionary description: type: string title: Optional human-readable description of this dictionary type title: Represents a dictionary/object value type with named fields v1ValueDictionaryTypeField: type: object properties: key: type: string title: The name/key of this field value: $ref: "#/components/schemas/v1ValueType" description: type: string title: Optional human-readable description of this field title: Represents a single field within a dictionary value type v1ValueUnionType: type: object properties: inners: type: array items: $ref: "#/components/schemas/v1ValueType" title: The possible value types in this union title: Represents a union value type that can be one of several possible types v1ValueOptionalType: type: object properties: inner: $ref: "#/components/schemas/v1ValueType" title: Represents a value type that can be optional (nullable) v1ValueGenericDictionaryType: type: object properties: key_type: $ref: "#/components/schemas/v1ValueType" value_type: $ref: "#/components/schemas/v1ValueType" title: Represent a generic dictionary that can hold any entry of a particular key and value type v1ValueAnyType: type: object title: Represents a value type that can hold any kind of value v1ValueScalarType: type: string enum: - VALUE_SCALAR_TYPE_UNSPECIFIED - VALUE_SCALAR_TYPE_TEXT - VALUE_SCALAR_TYPE_NUMBER - VALUE_SCALAR_TYPE_BOOLEAN - VALUE_SCALAR_TYPE_DATETIME - VALUE_SCALAR_TYPE_DATE - VALUE_SCALAR_TYPE_TIME - VALUE_SCALAR_TYPE_FILE - VALUE_SCALAR_TYPE_TIMEDELTA default: VALUE_SCALAR_TYPE_UNSPECIFIED description: |- - VALUE_SCALAR_TYPE_UNSPECIFIED: Unspecified value type - VALUE_SCALAR_TYPE_TEXT: A text value type - VALUE_SCALAR_TYPE_NUMBER: A number value type - VALUE_SCALAR_TYPE_BOOLEAN: A boolean value type - VALUE_SCALAR_TYPE_DATETIME: A datetime value type - VALUE_SCALAR_TYPE_DATE: A date value type - VALUE_SCALAR_TYPE_TIME: A time value type - VALUE_SCALAR_TYPE_FILE: A file value type - VALUE_SCALAR_TYPE_TIMEDELTA: A timedelta value type title: Supported Value Scalar Types v1ValueEnumType: type: object properties: is_a: type: string title: Semantic classification of what this enum represents members: type: array items: $ref: "#/components/schemas/v1ValueEnumTypeMember" title: The available options/members of this enum description: type: string title: Optional human-readable description of this enum type title: Represents an enumeration value type with predefined options v1ValueEnumTypeMember: type: object properties: name: type: string title: The programmatic name of this enum member description: type: string title: Optional human-readable description of this enum member title: Represents a single member/option within an enum value type v1CodeMapping: type: object properties: entries: type: array items: $ref: "#/components/schemas/v1CodeMappingEntry" description: >- List of mapping entries that associate SPy code regions with English code regions. Each entry defines a paired relationship between a span in the SPy code and a span in the English code representation. description: >- CodeMapping represents a bidirectional mapping between SPy (Subset-of-Python) code and English code locations within an automation. This mapping enables navigation between the two representations, facilitating debugging, traceability, and synchronized editing. Each entry in the mapping associates a region in the SPy code with its corresponding region in the English code. The mapping relationship is many-to-many and entries may overlap. required: - entries v1CodeMappingEntry: type: object properties: spy_location: $ref: "#/components/schemas/commonV1Location" english_location: $ref: "#/components/schemas/commonV1Location" description: >- CodeMappingEntry represents a single mapping between a region in SPy code and its corresponding region in English code. This bidirectional association allows navigation from SPy to English and vice versa, enabling synchronized views and debugging across both representations of the automation logic. required: - spy_location - english_location v1AutomationActivationState: type: string enum: - AUTOMATION_ACTIVATION_STATE_UNSPECIFIED - AUTOMATION_ACTIVATION_STATE_ACTIVE - AUTOMATION_ACTIVATION_STATE_DEACTIVATED default: AUTOMATION_ACTIVATION_STATE_UNSPECIFIED description: >- Activation state of a published automation. Controls whether the automation can execute published runs. - AUTOMATION_ACTIVATION_STATE_UNSPECIFIED: Unspecified state. Used when automation has no published version. Activation state is only meaningful after publishing. - AUTOMATION_ACTIVATION_STATE_ACTIVE: Automation is active and can execute published runs. - AUTOMATION_ACTIVATION_STATE_DEACTIVATED: Automation is deactivated and cannot execute published runs. Events will be logged but not executed. v1DisableAutomationScheduleResponse: type: object properties: schedule: $ref: "#/components/schemas/v1AutomationSchedule" description: DisableAutomationScheduleResponse contains the disabled schedule. v1AutomationSchedule: type: object properties: name: type: string title: >- Resource name of the schedule. Format: organizations/{org}/workspaces/{ws}/automations/{automation}/schedule config: $ref: "#/components/schemas/v1ScheduleConfig" enabled: type: boolean description: |- Whether the schedule is currently enabled. Disabled schedules do not trigger automation invocations. readOnly: true summary: type: string title: >- Human-readable summary of the schedule for display in the UI. Generated by the backend based on the schedule configuration. Examples: "Every weekday at 9:00 AM PT", "Monthly on the 4th Friday at 2:30 PM" readOnly: true next_run_times: type: array items: type: string format: date-time description: |- List of the next scheduled execution times. Useful for preview and verification. Backend generates these. readOnly: true remaining_occurrences: type: integer format: int32 description: >- Number of remaining occurrences if the schedule has an end condition. Only populated when config.end.end_type is SCHEDULE_END_TYPE_AFTER_OCCURRENCES. readOnly: true description: >- AutomationSchedule represents a schedule for invoking an automation. Each automation can have at most one schedule. Kestra is the source of truth. required: - config v1ScheduleConfig: type: object properties: start: $ref: "#/components/schemas/v1ScheduleStart" repeat_interval: $ref: "#/components/schemas/v1RepeatInterval" weekly_pattern: $ref: "#/components/schemas/v1DayOfWeekPattern" monthly_pattern: $ref: "#/components/schemas/v1DayOfMonthPattern" yearly_pattern: $ref: "#/components/schemas/v1MonthPattern" active_window: $ref: "#/components/schemas/v1TimeWindow" end: $ref: "#/components/schemas/v1ScheduleEnd" description: >- ScheduleConfig is the main user-friendly configuration for automation schedules. The backend generates the appropriate scheduling logic from this configuration. required: - start v1ScheduleEnd: type: object properties: end_type: $ref: "#/components/schemas/v1ScheduleEndType" end_date: $ref: "#/components/schemas/typeDate" max_occurrences: type: integer format: int32 description: >- Number of occurrences when end_type is SCHEDULE_END_TYPE_AFTER_OCCURRENCES. Schedule stops after this many executions. description: ScheduleEnd defines when the schedule stops running. required: - end_type v1ScheduleEndType: type: string enum: - SCHEDULE_END_TYPE_UNSPECIFIED - SCHEDULE_END_TYPE_NEVER - SCHEDULE_END_TYPE_ON_DATE - SCHEDULE_END_TYPE_AFTER_OCCURRENCES default: SCHEDULE_END_TYPE_UNSPECIFIED description: >- ScheduleEndType defines how a schedule terminates. - SCHEDULE_END_TYPE_UNSPECIFIED: Unspecified end type. Defaults to NEVER. - SCHEDULE_END_TYPE_NEVER: Schedule runs indefinitely (never ends). - SCHEDULE_END_TYPE_ON_DATE: Schedule ends on a specific date. - SCHEDULE_END_TYPE_AFTER_OCCURRENCES: Schedule ends after a specific number of occurrences. v1DayOfWeekPattern: type: object properties: days: type: array items: $ref: "#/components/schemas/v1DayOfWeek" description: |- Days of the week when the schedule should run. At least one day must be specified. description: |- DayOfWeekPattern specifies which days of the week to run. Used for weekly schedules (e.g., "every Monday", "every Mon/Wed/Fri"). required: - days v1DayOfWeek: type: string enum: - DAY_OF_WEEK_UNSPECIFIED - DAY_OF_WEEK_MONDAY - DAY_OF_WEEK_TUESDAY - DAY_OF_WEEK_WEDNESDAY - DAY_OF_WEEK_THURSDAY - DAY_OF_WEEK_FRIDAY - DAY_OF_WEEK_SATURDAY - DAY_OF_WEEK_SUNDAY default: DAY_OF_WEEK_UNSPECIFIED description: |- DayOfWeek represents days of the week for scheduling. Values align with ISO 8601 (Monday = 1, Sunday = 7). - DAY_OF_WEEK_UNSPECIFIED: Unspecified day. - DAY_OF_WEEK_MONDAY: Monday. - DAY_OF_WEEK_TUESDAY: Tuesday. - DAY_OF_WEEK_WEDNESDAY: Wednesday. - DAY_OF_WEEK_THURSDAY: Thursday. - DAY_OF_WEEK_FRIDAY: Friday. - DAY_OF_WEEK_SATURDAY: Saturday. - DAY_OF_WEEK_SUNDAY: Sunday. v1DayOfMonthPattern: type: object properties: day_number: type: integer format: int32 description: |- Run on a specific day of the month (1-31). If the month has fewer days, runs on the last day of that month. ordinal_day: $ref: "#/components/schemas/v1OrdinalDayOfWeek" description: |- DayOfMonthPattern specifies which day(s) of the month to run. Used for monthly schedules. v1OrdinalDayOfWeek: type: object properties: ordinal: $ref: "#/components/schemas/v1Ordinal" day: $ref: "#/components/schemas/v1DayOfWeek" description: >- OrdinalDayOfWeek represents a pattern like "first Monday" or "last Friday". Used as a building block for monthly and yearly patterns. required: - ordinal - day v1Ordinal: type: string enum: - ORDINAL_UNSPECIFIED - ORDINAL_FIRST - ORDINAL_SECOND - ORDINAL_THIRD - ORDINAL_FOURTH - ORDINAL_FIFTH - ORDINAL_LAST default: ORDINAL_UNSPECIFIED description: >- Ordinal represents the position within a period (e.g., "first Monday of month"). - ORDINAL_UNSPECIFIED: Unspecified ordinal. - ORDINAL_FIRST: First occurrence (e.g., first Monday). - ORDINAL_SECOND: Second occurrence. - ORDINAL_THIRD: Third occurrence. - ORDINAL_FOURTH: Fourth occurrence. - ORDINAL_FIFTH: Fifth occurrence (not all months have a fifth occurrence of each day). - ORDINAL_LAST: Last occurrence (e.g., last Friday of month). v1ScheduleStart: type: object properties: start_date: $ref: "#/components/schemas/typeDate" time: $ref: "#/components/schemas/typeTimeOfDay" time_zone: type: string description: >- Timezone for the schedule. Defaults to "UTC" if not specified. Use IANA timezone identifiers (e.g., "America/New_York", "America/Los_Angeles", "Europe/London"). description: ScheduleStart defines when the schedule begins. v1TimeWindow: type: object properties: start_time: type: string format: date-time description: The start time of the window (inclusive). end_time: type: string format: date-time description: The end time of the window (inclusive). time_zone: type: string description: >- The timezone for interpreting the time window. Format: IANA timezone identifier (e.g., "America/New_York", "Europe/London"). Defaults to "UTC" if not specified. window_start: $ref: "#/components/schemas/typeTimeOfDay" window_end: $ref: "#/components/schemas/typeTimeOfDay" description: Time window for querying insights. v1RepeatInterval: type: object properties: unit: $ref: "#/components/schemas/v1FrequencyUnit" interval: type: integer format: int32 description: >- The interval value. For example, 2 with FREQUENCY_UNIT_WEEK means "every 2 weeks". Must be a positive integer. Defaults to 1 if not specified. description: RepeatInterval defines how often the schedule repeats. required: - unit v1FrequencyUnit: type: string enum: - FREQUENCY_UNIT_UNSPECIFIED - FREQUENCY_UNIT_MINUTE - FREQUENCY_UNIT_HOUR - FREQUENCY_UNIT_DAY - FREQUENCY_UNIT_WEEK - FREQUENCY_UNIT_MONTH - FREQUENCY_UNIT_YEAR default: FREQUENCY_UNIT_UNSPECIFIED description: |- FrequencyUnit defines the unit for schedule repetition. - FREQUENCY_UNIT_UNSPECIFIED: Unspecified frequency unit. - FREQUENCY_UNIT_MINUTE: Schedule repeats every N minutes. - FREQUENCY_UNIT_HOUR: Schedule repeats every N hours. - FREQUENCY_UNIT_DAY: Schedule repeats every N days. - FREQUENCY_UNIT_WEEK: Schedule repeats every N weeks. - FREQUENCY_UNIT_MONTH: Schedule repeats every N months. - FREQUENCY_UNIT_YEAR: Schedule repeats every N years. v1MonthPattern: type: object properties: month: $ref: "#/components/schemas/v1Month" day_pattern: $ref: "#/components/schemas/v1DayOfMonthPattern" description: |- MonthPattern specifies which month and day to run. Used for yearly schedules (e.g., "July 30", "last Friday of December"). required: - month - day_pattern v1Month: type: string enum: - MONTH_UNSPECIFIED - MONTH_JANUARY - MONTH_FEBRUARY - MONTH_MARCH - MONTH_APRIL - MONTH_MAY - MONTH_JUNE - MONTH_JULY - MONTH_AUGUST - MONTH_SEPTEMBER - MONTH_OCTOBER - MONTH_NOVEMBER - MONTH_DECEMBER default: MONTH_UNSPECIFIED description: |- Month represents months of the year. - MONTH_UNSPECIFIED: Unspecified month. - MONTH_JANUARY: January. - MONTH_FEBRUARY: February. - MONTH_MARCH: March. - MONTH_APRIL: April. - MONTH_MAY: May. - MONTH_JUNE: June. - MONTH_JULY: July. - MONTH_AUGUST: August. - MONTH_SEPTEMBER: September. - MONTH_OCTOBER: October. - MONTH_NOVEMBER: November. - MONTH_DECEMBER: December. v1CountExceptionsByAutomationResponse: type: object properties: automation_counts: type: array items: $ref: "#/components/schemas/v1ExceptionAutomationCount" description: Exception counts by automation. next_page_token: type: string description: |- Token to retrieve the next page of results. Empty when there are no more results. total_size: type: integer format: int32 description: |- Total number of automations with exceptions (across all pages). Respects the filter from the request. total_exception_count: type: integer format: int32 description: >- Total count of all exceptions across all automations. Respects the filter from the request. This is the sum of all counts in automation_counts (across all pages). Useful for displaying summary statistics like "500 total exceptions across 25 automations". description: Response containing exception counts by automation. v1ExceptionAutomationCount: type: object properties: automation: type: string title: >- The automation resource name. Format: organizations/{organization}/workspaces/{workspace}/automations/{automation} count: type: integer format: int32 description: Number of exceptions for this automation. description: Exception count for a specific automation. v1ListDefaultInputsHistoryResponse: type: object properties: default_inputs_history_entries: type: array items: $ref: "#/components/schemas/v1DefaultInputsHistoryEntry" description: The history entries, ordered newest first. next_page_token: type: string description: Token for retrieving the next page. Empty if no more results. description: ListDefaultInputsHistoryResponse contains a paginated list of default input history entries. v1DefaultInputsHistoryEntry: type: object properties: default_inputs: type: object additionalProperties: $ref: "#/components/schemas/commonV1Value" description: The default inputs snapshot at the time of this change. readOnly: true change_time: type: string format: date-time description: When this change was made. readOnly: true change_actor: type: string description: User ID of the person who made this change. readOnly: true description: DefaultInputsHistoryEntry represents a single default input change event. v2RetrieveBooksConnectionsResponse: type: object properties: book_connections: type: array items: $ref: "#/components/schemas/v2BookConnectionDescriptor" title: The list of book connections next_page_token: type: string description: The token to use to retrieve the next page of connections. v2AddWorkspaceBookConnectionTriggerInstanceResponse: type: object properties: trigger_instance: $ref: "#/components/schemas/v2TriggerInstance" v2TriggerInstance: type: object properties: id: type: string title: The identifier of the trigger instance name: type: string title: The name of the trigger instance reference: type: string title: The reference of the trigger instance book_name: type: string title: The name of the book connection_id: type: string title: The identifier of the book connection trigger_id: type: string title: The name of the trigger configuration: type: object additionalProperties: $ref: "#/components/schemas/bdkV2Value" title: Configuration parameters for the trigger endpoint: type: string title: The endpoint of the trigger instance automation_ids: type: array items: type: string title: Automation IDs workspace_id: type: string title: Workspace ID organization_id: type: string title: Organization ID filter_expression: $ref: "#/components/schemas/v2Expression" status: $ref: "#/components/schemas/v2TriggerInstanceStatus" v2TriggerInstanceStatus: type: object properties: state: $ref: "#/components/schemas/v2TriggerInstanceState" state_category: $ref: "#/components/schemas/v2TriggerInstanceStateCategory" reason: type: string title: Human-readable message providing additional details about the current state last_updated: type: string title: RFC 3339 timestamp of when the status was last updated title: Status information for a BookConnection v2TriggerInstanceStateCategory: type: string enum: - TRIGGER_INSTANCE_STATE_CATEGORY_WARNING - TRIGGER_INSTANCE_STATE_CATEGORY_READY - TRIGGER_INSTANCE_STATE_CATEGORY_FAILED default: TRIGGER_INSTANCE_STATE_CATEGORY_WARNING title: The category/level of the connection state v2TriggerInstanceState: type: string enum: - TRIGGER_INSTANCE_STATE_PENDING - TRIGGER_INSTANCE_STATE_READY - TRIGGER_INSTANCE_STATE_FAILED - TRIGGER_INSTANCE_STATE_UNKNOWN default: TRIGGER_INSTANCE_STATE_PENDING title: Possible phases for a TriggerInstance (Pending, Ready, Failed, Unknown) v2RetrieveBookVersionsResponse: type: object properties: versions: type: array items: type: string title: All available versions for the specified book v1GenerateUploadUrlResponse: type: object properties: upload_uri: type: string title: Presigned upload URI title: Response with presigned upload URL v2SearchBooksResponse: type: object properties: results: type: array items: $ref: "#/components/schemas/v2SearchBookMatch" title: Ranked list of book matches for the given query title: Search results for books v2SearchBookMatch: type: object properties: book: $ref: "#/components/schemas/v2BookDescriptor" score: type: number format: double title: Relevance score (higher is better) title: A match result for a searched book v2BookDescriptor: type: object properties: id: type: string description: "@deprecated, use name and version to uniquely identify a book" title: The identifier of the book (a.k.a integration_id) name: type: string title: The name of the book short_description: type: string title: Short description of the book long_description: type: string title: Short description of the book author: type: string title: Author of the book icon: type: string format: byte title: Icon of the book in an image format that is web-compatible (i.e. JPG, PNG, SVG, WebP) version: type: string title: Version of the book authentications: type: array items: $ref: "#/components/schemas/v2BookAuthenticationDescriptor" title: Authentication mechanism for a book version configurations: type: array items: $ref: "#/components/schemas/v2ConceptDescriptor" title: "All the parameters available for configuring the behaviour of this book. Note: replaced by config_map" display_name: type: string title: Display name of the book endpoint: type: string title: URI location of the book, such as lambda://microsoft/1.0.4 connection_required: type: boolean description: Connection Required. True if all procedures always require a connection. discover_capable: type: boolean title: True if the book is capable of discovering book procedures tags: type: array items: type: string title: Tags associated with the book procedures: type: array items: $ref: "#/components/schemas/v2BookProcedureDescriptor" title: Book procedures noun_phrase: $ref: "#/components/schemas/v2NounPhrase" userinfo_capable: type: boolean title: True if the book is capable of returning oauth user's info triggers: type: array items: $ref: "#/components/schemas/v2BookTriggerDescriptor" title: Book triggers bdk_runtime_version: type: string title: BDK Runtime version environment_information: $ref: "#/components/schemas/bdkV2EnvironmentInformation" config_map: type: object additionalProperties: $ref: "#/components/schemas/v2ConceptDescriptor" title: All the parameters available for configuring the behaviour of this book hidden: type: boolean title: True if the book is hidden polls: type: array items: $ref: "#/components/schemas/v2BookPollDescriptor" title: Book polls supports_remote_secret: type: boolean description: |- True if this book's runtime can resolve connection credentials from a managed secret store (referenced by credential id) instead of inline authentication values. Runtime-injected — a book gains this by running on a capable runtime. Absent/false = legacy (inline authentication only). bdkV2EnvironmentInformation: type: object properties: version: type: string runtime_name: type: string title: Runtime name runtime_version: type: string title: Runtime version bci_protocol_version: type: string title: BCI Protocol version api_version: type: string title: BDK API Version path: type: array items: type: string title: Book path under which books will be discovered title: Information about the environment v2BookProcedureDescriptor: type: object properties: id: type: string title: Id of the procedure to use in subsequent calls signature: $ref: "#/components/schemas/v2BookProcedureSignature" inputs: type: array items: $ref: "#/components/schemas/v2ConceptDescriptor" title: All the inputs for the procedure (required and non required) outputs: type: array items: $ref: "#/components/schemas/v2ConceptDescriptor" title: All the outputs for the procedure short_description: type: string title: Short description long_description: type: string title: Longer description filter_capable: type: boolean title: Can this procedure filter its response? page_capable: type: boolean title: Can this procedure page its response? connection_required: $ref: "#/components/schemas/v2ConnectionRequired" is_discovered: type: boolean title: True if the procedure was discovered questions: type: array items: $ref: "#/components/schemas/v2QuestionDescriptor" title: Questions the procedure may ask examples: type: array items: $ref: "#/components/schemas/v2ExampleDescriptor" title: Examples of procedure usage is_async: type: boolean title: Does the procedure return a promise? is_mutation: type: boolean title: True if the procedures performs a mutating action search_hints: type: array items: type: string title: Search hints used for procedure resolution spy_signature: $ref: "#/components/schemas/v2SpySignatureDescriptor" v2BookProcedureSignature: type: object properties: english: type: string verbs: type: array items: type: string title: Verb of the signature object: $ref: "#/components/schemas/v2NounPhrases" preposition: type: string title: Preposition target: $ref: "#/components/schemas/v2NounPhrases" outputs: type: array items: $ref: "#/components/schemas/v2NounPhrases" title: Outputs proper_nouns: type: array items: type: string title: All the proper nouns that appear on this signature v2ExampleDescriptor: type: object properties: description: type: string title: The description of the example snippet: type: string title: The example snippet v2ConnectionRequired: type: string enum: - Optional - Always - Never default: Optional title: Connection required v2QuestionDescriptor: type: object properties: noun_phrases: $ref: "#/components/schemas/v2NounPhrases" type: $ref: "#/components/schemas/v2ConceptType" v2ConceptType: type: object properties: scalar_type: $ref: "#/components/schemas/v2ConceptScalarType" optional_type: $ref: "#/components/schemas/v2ConceptOptionalType" list_type: $ref: "#/components/schemas/v2ConceptListType" dictionary_type: $ref: "#/components/schemas/v2ConceptDictionaryType" table_type: $ref: "#/components/schemas/v2ConceptTableType" opaque_type: $ref: "#/components/schemas/v2ConceptOpaqueType" any_type: $ref: "#/components/schemas/v2ConceptAnyType" union_type: $ref: "#/components/schemas/v2ConceptUnionType" self_type: $ref: "#/components/schemas/v2ConceptSelfType" sensitive_type: $ref: "#/components/schemas/v2ConceptSensitiveType" enum_type: $ref: "#/components/schemas/v2ConceptEnumType" v2ConceptOpaqueType: type: object properties: is_a: type: array items: $ref: "#/components/schemas/v2NounPhrase" description: type: string v2ConceptUnionType: type: object properties: inners: type: array items: $ref: "#/components/schemas/v2ConceptType" v2ConceptSensitiveType: type: object properties: inner: $ref: "#/components/schemas/v2ConceptType" v2ConceptOptionalType: type: object properties: inner: $ref: "#/components/schemas/v2ConceptType" v2ConceptEnumType: type: object properties: is_a: type: array items: $ref: "#/components/schemas/v2NounPhrase" members: type: array items: $ref: "#/components/schemas/v2ConceptEnumTypeMember" description: type: string v2ConceptEnumTypeMember: type: object properties: name: type: string noun_phrase: $ref: "#/components/schemas/v2NounPhrase" description: type: string v2ConceptScalarType: type: string enum: - ConceptScalarTypeConceptual - ConceptScalarTypeText - ConceptScalarTypeNumber - ConceptScalarTypeBoolean - ConceptScalarTypeDatetime - ConceptScalarTypeDate - ConceptScalarTypeTime - ConceptScalarTypeFile - ConceptScalarTypeUUID default: ConceptScalarTypeConceptual title: Supported concept types v2ConceptSelfType: type: object v2ConceptAnyType: type: object v2ConceptDictionaryType: type: object properties: is_a: type: array items: $ref: "#/components/schemas/v2NounPhrase" fields: type: array items: $ref: "#/components/schemas/v2ConceptDictionaryTypeField" description: type: string v2ConceptDictionaryTypeField: type: object properties: key: type: string value: $ref: "#/components/schemas/v2ConceptType" description: type: string v2ConceptTableType: type: object properties: columns: type: array items: $ref: "#/components/schemas/v2ConceptTableTypeColumn" description: type: string v2ConceptTableTypeColumn: type: object properties: key: type: string value: $ref: "#/components/schemas/v2ConceptType" description: type: string v2ConceptListType: type: object properties: inner: $ref: "#/components/schemas/v2ConceptType" v2ConceptDescriptor: type: object properties: noun_phrases: $ref: "#/components/schemas/v2NounPhrases" type: $ref: "#/components/schemas/v2ConceptType" description: type: string title: Description default_value: $ref: "#/components/schemas/bdkV2Value" v2BookTriggerDescriptor: type: object properties: id: type: string title: The identifier of the trigger name: type: string title: The name of the trigger description: type: string title: Description of the trigger setup_description: type: string title: Setup description for the trigger configuration: type: object additionalProperties: $ref: "#/components/schemas/v2ConceptDescriptor" title: Configuration parameters for the trigger filter_capable: type: boolean title: True if the trigger is capable of filtering events is_manual: type: boolean title: True if the trigger is manually invoked event_type: type: object additionalProperties: $ref: "#/components/schemas/v2ConceptDescriptor" title: Event type schema for the trigger is_shared_endpoint: type: boolean description: True if every trigger instance of this trigger shares the same endpoint when configured. v2BookPollDescriptor: type: object properties: id: type: string title: The identifier of the poll name: type: string title: The name of the poll description: type: string title: Description of the poll configuration: type: object additionalProperties: $ref: "#/components/schemas/v2ConceptDescriptor" title: Configuration parameters for the poll event_type: type: object additionalProperties: $ref: "#/components/schemas/v2ConceptDescriptor" title: Event type schema for the poll filter_capable: type: boolean title: True if the poll is capable of filtering events at the source v2BookAuthenticationDescriptor: type: object properties: custom: $ref: "#/components/schemas/v2BookCustomAuthenticationDescriptor" oauth: $ref: "#/components/schemas/v2BookOAuthAuthenticationDescriptor" secret_type_id: type: string description: |- Optional secret type id this auth method's credential conforms to. Lets a book share a credential shape across books/services (e.g. "anthropic_api_key") instead of the per-book default. When unset, the default `bdk.{book}.{authId}` is used. Lives on the wrapper (not per-variant) so it covers custom and oauth alike. v2BookOAuthAuthenticationDescriptor: type: object properties: id: type: string description: |- Since books can have multiple authentication mechanisms there is and ID to differentiate each mechanism. provider: $ref: "#/components/schemas/v2OAuthProvider" flows: type: array items: $ref: "#/components/schemas/v2OAuthFlow" title: Supported OAuth flows authorize_endpoint: type: string title: Authorize endpoint token_endpoint: type: string title: Token endpoint scope: type: array items: type: string title: Scopes name: type: string title: A name for the authentication arguments: type: array items: $ref: "#/components/schemas/v2OAuthArgumentDescriptor" title: |- Additional arguments which are not part of the OAuth specification but are required for the authentication to work (such as tenant_id) credentials: type: array items: $ref: "#/components/schemas/v2CredentialDescriptor" title: Credential descriptors preferred: type: boolean title: If this is a preferred authentication method parameter_mapping: type: object additionalProperties: type: string description: |- Optional mapping of standard OAuth parameter names to provider-specific names. For example, Slack requires scopes to be sent as "user_scope" instead of "scope" on the authorize URL: { "scope": "user_scope" } The runtime uses this to rename parameters when constructing the authorize and token exchange requests. deprecated: type: boolean title: If this authentication method is deprecated v2CredentialDescriptor: type: object properties: id: type: string title: Id of the credential type: $ref: "#/components/schemas/v2CredentialType" label: type: string title: Label that will be displayed to the user during configuration of the book visible: type: boolean description: True if the value is visible to the book, false otherwise. description: type: string title: Description v2CredentialType: type: string enum: - CredentialTypeText - CredentialTypeSensitiveText - CredentialTypeSensitiveDictionary default: CredentialTypeText title: Supported configuration types v2OAuthArgumentDescriptor: type: object properties: id: type: string title: Id of the parameter name: type: string title: Name of the parameter description: type: string title: Description of the parameter v2OAuthProvider: type: string enum: - OAuthProviderMicrosoft - OAuthProviderGoogle - OAuthProviderGeneric default: OAuthProviderMicrosoft title: Supported OAuth providers v2OAuthFlow: type: string enum: - OAuthFlowAuthorizationCode - OAuthFlowClientCredentials default: OAuthFlowAuthorizationCode title: Supported OAuth flows v2BookCustomAuthenticationDescriptor: type: object properties: id: type: string description: |- Since books can have multiple authentication mechanisms there is and ID to differentiate each mechanism. credentials: type: array items: $ref: "#/components/schemas/v2CredentialDescriptor" title: Credentials required to perform authentication description: type: string title: A description of the authentication name: type: string title: A name for the authentication noun_phrase: $ref: "#/components/schemas/v2NounPhrase" preferred: type: boolean title: If this is a preferred authentication method deprecated: type: boolean title: If this authentication method is deprecated v2RetrieveUserInfoResponse: type: object properties: user_info: $ref: "#/components/schemas/v2UserInfo" title: The response to a retrieve user info request v2UserInfo: type: object properties: email: type: string title: The email of the user username: type: string title: The username of the user other_attributes: type: object additionalProperties: type: string title: A map with other extra attributes the user may have v2RetrieveBookResponse: type: object properties: book: $ref: "#/components/schemas/v2BookDescriptor" v2SearchBooksRequest: type: object properties: query: type: string title: Free-text search query to match against book name, version, tags, or descriptions top_k: type: integer format: int64 title: Maximum number of results to return max_distance: type: number format: float title: Maximum distance threshold for similarity matching title: Search for books across the library v1Exception: type: object properties: name: type: string title: >- The full resource name of the exception. Format: organizations/{organization_id}/workspaces/{workspace_id}/exceptions/{exception_id} run: type: string title: >- The run in which the exception occurred. The run must belong to the same workspace as the exception. Format: organizations/{organization}/workspaces/{workspace}/automations/{automation}/runs/{run} location: $ref: "#/components/schemas/commonV1Location" message: type: string description: The exception message generated by the interpreter. create_time: type: string format: date-time description: The timestamp of when the exception was created. readOnly: true update_time: type: string format: date-time description: The timestamp of when the exception was last updated. readOnly: true state: $ref: "#/components/schemas/v1ExceptionState" automation: type: string title: >- The automation that the exception belongs to. The automation of an exception is the automation that the run belongs to. Format: organizations/{organization}/workspaces/{workspace}/automations/{automation} readOnly: true description: type: string description: >- A human-friendly description of the exception. Generated by the exception service. Recently created exceptions may not yet have a description. readOnly: true group: type: string description: >- Groups are used to categorize exceptions Currently support static groups: "missing_values", "user_system_error", "internal_error" Format: organizations/{organization_id}/workspaces/{workspace_id}/exceptionGroups/missing_values Format: organizations/{organization_id}/workspaces/{workspace_id}/exceptionGroups/user_system_error Format: organizations/{organization_id}/workspaces/{workspace_id}/exceptionGroups/internal_error In future, we may support dynamic groups. Empty string means the exception is not grouped. resolution_guide_entry: type: string title: >- The guide entry that was used to automatically resolve this exception. Set when the exception service successfully applies a guide entry to resolve the exception i.e exception.state should be RESOLVED if this field is set. Format: organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/guideEntries/{guide_entry_id} readOnly: true stage: $ref: "#/components/schemas/v1AutomationStage" execution_id: type: string title: >- The execution ID within the run where this exception occurred. Used to differentiate exceptions at the same location with the same message. Example: "exec_123abc" or a UUID extra: type: object additionalProperties: type: string description: Extra information about the exception. assignee: type: string title: |- The user assigned to resolve this exception. Format: users/{user} resolver: type: string description: >- The entity that resolved this exception. Can be either a user (for manual resolutions) or an agent (for automatic resolutions). Format: users/{user} or agents/{agent} Note: No resource_reference is specified to avoid service dependencies and to support multiple resource types in a single field. title: type: string description: |- Short, business-friendly title for the exception. Generated by the exception service (LLM) at create time alongside ``description``, and intended to be the primary one-line label that clients render in lists, tooltips, and notifications. May be empty for older exceptions that pre-date title generation. readOnly: true step_index: type: integer format: int32 description: |- 1-based index of the ``# @step`` block in the automation source that contains the failing line for this exception. Zero (the proto default) means the exception did not fall inside a step block (the automation had no step markers, or the failing line fell outside any covered range). Clients should treat zero as "no step". Deprecated: no replacement. Still populated for existing clients; will stop being set in a future release. Do not build new behavior on it. readOnly: true step_title: type: string description: |- Human-readable label of the ``# @step`` block that contains the failing line (paired with ``step_index``). Empty when ``step_index`` is zero or when the step block has no title. Deprecated: no replacement. Still populated for existing clients; will stop being set in a future release. Do not build new behavior on it. readOnly: true code: type: string description: |- The SPY/AOP code content at the location where the exception occurred. Provided by the caller at creation time and not stored or returned. connections: type: object additionalProperties: $ref: "#/components/schemas/v1BookConnection" description: |- The book connections that were active at the time this exception occurred. Provided by the caller at creation time and not stored or returned. Maps connection names to their specific ID and endpoints, mirroring the book_connections field on the run's executable steps. rain_thread_id: type: string description: |- The Rain thread ID for this exception on the Astral-on-Rain path. Each exception gets its own Rain thread so clients can subscribe to just this exception's events. Empty on the local path or when Rain is disabled. readOnly: true is_source_fix_required: type: boolean description: |- Whether resolving this exception requires a fix to the automation source. Deprecated: no replacement. Still populated for existing clients; will stop being set in a future release. Do not build new behavior on it. Note this deprecates only the field on Exception -- the same-named request fields on MarkExceptionResolvedRequest and PatchStepRequest are unaffected. readOnly: true runtime_values: type: object additionalProperties: $ref: "#/components/schemas/commonV1Value" description: |- The runtime values of the variables of the function which contains failing sentence read, and the values they held (variable name -> value). Sourced from Jarvis ``ExecutionFailed.error.context.runtime_values`` and forwarded by Jeeves. Provided by the caller at creation time and not stored or returned, mirroring ``connections``. Empty is a legitimate state: parse errors, timeouts and panics carry no runtime values, and neither does a pre-v3.6.0 Jarvis. cluster: type: string description: |- Generic symptom label for this exception, with every specific value (names, numbers, dates, file names) stripped out, so that two runs which failed the same way share one ``cluster``. Generated by the exception service (LLM) at create time in the same call as ``title`` and ``description``. Clients use it to group same-symptom exceptions. May be empty for older exceptions that pre-date cluster generation. readOnly: true runtime_identifier: type: string description: |- The single runtime value responsible for this exception -- one scalar such as a name, number, code or date -- which differentiates this exception from the others in its ``cluster``. Generated by the exception service (LLM) alongside ``cluster``. Empty is a legitimate state: it means no single value is responsible (and it is also empty for older exceptions that pre-date runtime identifier generation). readOnly: true typed_extra: type: object additionalProperties: $ref: "#/components/schemas/commonV1Value" description: Extra information about the exception, as typed values that may be offloaded. description: >- An exception that occurred during an automation run. Exceptions are raised by the interpreter and are analogous to Python exceptions. However, the Kognitos platform provides various mechanisms to resolve an exception and then resume the run. Automation runs are important business processes for our users, so the expectation is that every exception needs to be resolved even if the resolution involves manual steps or abandoning the automation run. required: - run - location - message v1ExceptionState: type: string enum: - EXCEPTION_STATE_UNSPECIFIED - EXCEPTION_STATE_PENDING - EXCEPTION_STATE_RESOLVED - EXCEPTION_STATE_ARCHIVED default: EXCEPTION_STATE_UNSPECIFIED description: >- The state of an exception. - EXCEPTION_STATE_UNSPECIFIED: The state is not specified. - EXCEPTION_STATE_PENDING: The exception is pending resolution. This is the initial state when an exception is created. Transitions: On creation --> PENDING PENDING --> RESOLVED: Exception successfully resolved (run can continue) PENDING --> ARCHIVED: Exception archived without resolution (run abandoned) - EXCEPTION_STATE_RESOLVED: The exception has been resolved. RESOLVED is a terminal state. Resolved exceptions are retained for historical records Transitions: PENDING --> RESOLVED: Exception resolved (run can continue) - EXCEPTION_STATE_ARCHIVED: The exception has been archived. Archived exceptions are retained for historical records and audit purposes. Transitions: PENDING --> ARCHIVED: Exception archived without resolution (run abandoned) ARCHIVED --> PENDING: Exception unarchived (run can continue) v2RetrieveBookConceptsResponse: type: object properties: concepts: type: array items: $ref: "#/components/schemas/v2ConceptDescriptor" title: Available concepts title: Retrieve all the available concept descriptors for a book v1CredentialInfo: type: object properties: book: type: string description: |- The name of the book requiring credentials. This field represents the book name. book_version: type: string description: The version of the book. connection_alias: type: string description: |- The alias of the connection within the automation. This field represents the connection alias. connection_id: type: string description: The unique identifier of the connection. phase_type: $ref: "#/components/schemas/v1PhaseType" description: CredentialInfo describes connection credential information. required: - book - book_version v1ListOrganizationUsersResponse: type: object properties: users: type: array items: $ref: "#/components/schemas/v1UserWithRoles" description: The list of users in the organization 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 `ListOrganizationUsers` 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 an organization. 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). workspace_ids: type: array items: type: string description: |- IDs of workspaces in which the user has any active workspace-scoped role. Empty if the user only holds org-scoped roles (which grant implicit access to all workspaces in the org). Used by Org-Settings Users tab to render the "Workspaces" column ("2 workspaces" / "All workspaces" / specific name). 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. 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 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. - ROLE_SCOPE_UNSPECIFIED: Unspecified role scope. - ROLE_SCOPE_ORGANIZATION: Role applies at the organization level. - ROLE_SCOPE_WORKSPACE: Role applies at the workspace level. 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. last_active_time: type: string format: date-time description: |- The most recent timestamp the user was seen on an authenticated request. Output-only; written debounced on auth events, so it is accurate to within a few minutes rather than to the request. Unset when the user has not been seen since the field was introduced — there is no backfill, so clients should render an em-dash rather than an epoch date. Mirrors `User.last_active_time`; surfaced here so the Org/Workspace Settings Users tables can render the "Last active" column from a single list call. readOnly: true description: >- Contains basic information about a user. This is a lightweight representation used when full user details are not needed. 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. v2RetrieveBookProceduresResponse: type: object properties: procedures: type: array items: $ref: "#/components/schemas/v2BookProcedureDescriptor" title: Available procedures title: Retrieve all the available signatures for a book v1ConnectionReplacement: type: object properties: old_connection_id: type: string description: |- The current connection ID to replace. This connection ID must exist in the automation. new_connection_id: type: string title: |- The new connection ID to use as replacement. This connection must: - Exist in the workspace - Have the same book_name as the old connection - Have the same book_version as the old connection connection_alias: type: string description: |- The alias of the connection to use as replacement. This alias must be unique within the automation. description: ConnectionReplacement specifies replacing one connection ID with another. required: - old_connection_id - new_connection_id - connection_alias 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. dashboardsQueryAutomationEstimatesResponse: type: object properties: workspace_estimates: type: object additionalProperties: $ref: "#/components/schemas/dashboardsAutomationEstimateList" title: >- Automation estimates grouped per workspace. Key: workspace_id (format: organizations/{org}/workspaces/{workspace}) readOnly: true description: |- Response message for QueryAutomationEstimates method. Contains automation estimates grouped by workspace. dashboardsAutomationEstimateList: type: object properties: estimates: type: array items: $ref: "#/components/schemas/dashboardsAutomationEstimate" description: List of automation estimates for a workspace. readOnly: true description: Wrapper for a list of automation estimates. dashboardsAutomationEstimate: type: object properties: automation_id: type: string title: >- The automation ID this estimate applies to. Format: organizations/{organization}/workspaces/{workspace}/automations/{automation} cost_usd: type: string description: The estimated cost saved per run in USD. time_saved_secs: type: integer format: int32 description: The estimated time saved per run in seconds. description: AutomationEstimate represents the estimated value metrics for an automation. required: - automation_id - cost_usd - time_saved_secs v1CancelGenerationResponse: type: object description: |- Response for canceling ongoing event generation. Empty response. Reserved for future extensibility. 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. 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 org-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 instead of matching on the non-unique `workspace_display_name`. Unset when the 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 `role_template_ids` for display: that field lists built-in templates only, while this also covers workspace custom roles. readOnly: true description: |- A UserInvitation represents a pending invitation summary returned by `ListOrganizationUserInvites` / `ListWorkspaceUserInvites`. Previously this message only carried `email` and `invitation_id`; the admin Invitations table in the v2.2 mocks needs role(s) and workspace too, so those are surfaced here directly to avoid one `GetInvitation` per row. v2RetrieveBookConnectionResponse: type: object properties: book_connection: $ref: "#/components/schemas/v2BookConnectionDescriptor" v1EnableAutomationScheduleResponse: type: object properties: schedule: $ref: "#/components/schemas/v1AutomationSchedule" description: EnableAutomationScheduleResponse contains the enabled schedule. 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: {} v2SearchWorkspaceBookProceduresResponse: type: object properties: results: type: array items: $ref: "#/components/schemas/v2SearchWorkspaceBookProcedureMatch" title: Ranked list of matches for the given query title: Search results for workspace book procedures (static and discovered) v2SearchWorkspaceBookProcedureMatch: type: object properties: book_name: type: string title: Book name owning the procedure book_version: type: string title: Book version owning the procedure procedure: $ref: "#/components/schemas/v2BookProcedureDescriptor" score: type: number format: double title: Relevance score (higher is better) organization_id: type: string title: Organization ID workspace_id: type: string title: Workspace ID connection_id: type: string title: Connection ID connection_name: type: string title: Human-readable connection name (as set by the user) title: A match result for a searched procedure (static or discovered) v1CurrentUserOrganizationsResponse: type: object properties: user_organizations: type: array items: $ref: "#/components/schemas/v1Organization" description: The list of organizations the current user is a member of. 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 `CurrentUserOrganizations` to get the next page of results. If this field is empty, it means there are no more results. description: Response message for listing organizations for the current user. v1Organization: type: object properties: name: type: string description: >- The resource name of the organization. Format: organizations/{organization_id} 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 organization. logo_data_uri: type: string title: |- The organization logo as a data URI following RFC 2397. Format: data:[][;encoding], Example: data:image/png;encoding, create_time: type: string format: date-time description: The timestamp when the organization was created. readOnly: true update_time: type: string format: date-time description: The timestamp when the organization was last updated. readOnly: true owner_display_name: type: string description: The display name of the organization owner. readOnly: true owner_email: type: string description: The email address of the organization owner. readOnly: true description: An Organization is the top-level resource container. required: - title 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" show_bounding_boxes: type: boolean description: |- Whether document viewers in the workspace draw bounding boxes around extracted values; true by default. description: Represents workspace-specific settings or preferences. 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. Valid range [0, 10]. Marked `optional` so that 0 (a legitimate user choice meaning "integer display") can be distinguished from "field not set". Wire format is identical to a plain `int32` in proto3 — old clients that omit 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`). Empty string indicates inherit-from-parent-scope or system default. description: |- General preferences for display and formatting. Used by both workspace and organization preferences, and embedded in UserPreferences 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. - TIME_FORMAT_UNSPECIFIED: Unspecified time format. - TIME_FORMAT_12_HOUR: 12-hour format (1:00 PM). - 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. - DATE_FORMAT_UNSPECIFIED: Unspecified date format. - DATE_FORMAT_DD_MM_YYYY_SLASH: DD/MM/YYYY format. - DATE_FORMAT_MM_DD_YYYY_SLASH: MM/DD/YYYY format. - DATE_FORMAT_YYYY_MM_DD_DASH: YYYY-MM-DD format (ISO 8601). - DATE_FORMAT_DD_MM_YYYY_DASH: DD-MM-YYYY format. - DATE_FORMAT_MM_DD_YYYY_DASH: MM-DD-YYYY format. - DATE_FORMAT_YYYY_MM_DD_SLASH: YYYY/MM/DD format. - DATE_FORMAT_DD_MM_YYYY_DOT: DD.MM.YYYY format (European style). - DATE_FORMAT_MM_DD_YYYY_DOT: MM.DD.YYYY format. - DATE_FORMAT_YYYY_MM_DD_DOT: YYYY.MM.DD format. - DATE_FORMAT_DD_MMM_YYYY: DD MMM YYYY format (e.g., 15 Jan 2024). - DATE_FORMAT_MMM_DD_YYYY: MMM DD, YYYY format (e.g., Jan 15, 2024). - DATE_FORMAT_DD_MMMM_YYYY: DD MMMM YYYY format (e.g., 15 January 2024). - 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. - DECIMAL_SYMBOL_UNSPECIFIED: Unspecified decimal symbol. - DECIMAL_SYMBOL_PERIOD: Period (.) as decimal separator. - 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. - MEASUREMENT_SYSTEM_UNSPECIFIED: Unspecified measurement system. - MEASUREMENT_SYSTEM_METRIC: Metric system. - MEASUREMENT_SYSTEM_IMPERIAL: Imperial system. v1CountExceptionsByGroupResponse: type: object properties: group_counts: type: array items: $ref: "#/components/schemas/v1ExceptionGroupCount" description: Exception counts by group, including metadata for each group. next_page_token: type: string description: |- Token to retrieve the next page of results. Empty when there are no more results. total_size: type: integer format: int32 description: |- Total number of groups with exceptions (across all pages). Respects the filter from the request. total_exception_count: type: integer format: int32 description: >- Total count of all exceptions across all groups. Respects the filter from the request. This is the sum of all counts in group_counts (across all pages). Useful for displaying summary statistics like "110 total exceptions across 3 groups". description: Response containing exception counts by group. v1ExceptionGroupCount: type: object properties: group: $ref: "#/components/schemas/v1ExceptionGroup" count: type: integer format: int32 description: Number of exceptions in this group. description: Exception count for a specific group, including group metadata. v1ExceptionGroup: type: object properties: name: type: string description: >- The static types (e.g., "missing_values", "user_system_error", "internal_error"). group name is fully qualified Format: organizations/{organization_id}/workspaces/{workspace_id}/exceptionGroups/missing_values Format: organizations/{organization_id}/workspaces/{workspace_id}/exceptionGroups/user_system_error Format: organizations/{organization_id}/workspaces/{workspace_id}/exceptionGroups/internal_error This is maintained by the system until we promote these to full resources. This is the value used in the Exception.group field. title: type: string description: Human-readable display name for UI. description: type: string description: Description of what this group represents. suggested_action: type: string description: Suggested action to resolve exceptions in this group. default_assignee: type: string title: >- Default assignee for new exceptions in this group. When set, new exceptions in this group will be automatically assigned to this user. Empty string means no default assignee is set. Format: users/{user} description: >- Groups are not full resources and cannot be created or modified via the API (for now) In future, we may promote these to full resources. v1QueryMetricsResponse: type: object properties: results: type: array items: $ref: "#/components/schemas/v1MetricResult" description: |- Results for each requested metric. Ordered in the same sequence as the metrics field in the request. Each result contains the time series data for one metric. readOnly: true next_page_token: type: string description: |- Token for retrieving the next page of results. If non-empty, there are more results available. Pass this value as page_token in the next request to retrieve the next page. If empty, there are no more results (this is the last page). When paginating, all metrics will include their next page of series. See https://google.aip.dev/158 for pagination specification. readOnly: true description: |- Response message for the QueryMetrics RPC. Contains results for each requested metric, with time series data and metadata about the query execution. required: - results v1MetricResult: type: object properties: metric: type: string description: |- The name of this metric. Echoes back the metric name from the request. readOnly: true interval: $ref: "#/components/schemas/v1MetricInterval" aggregation: $ref: "#/components/schemas/v1AggregationFunction" series: type: array items: $ref: "#/components/schemas/v1MetricSeries" description: >- Multiple time series, one per unique group_by combination. If group_by is empty, there will be exactly one series with empty tags. If group_by has values, there will be one series per unique combination found in the data. Series are ordered according to the order_by parameter in the request. If page_size was specified, results are paginated across all metrics. The list may be empty if no data exists for the requested time range. readOnly: true description: |- Result for a single metric query. Contains the time series data and metadata for one metric. required: - metric - interval - aggregation - series v1MetricSeries: type: object properties: tags: type: object additionalProperties: type: string description: >- Tags identifying this series. The unique combination of group_by tag values that define this series. If group_by is empty, this will be an empty map. Example: {"status": "success", "workspace_id": "ws_123"} readOnly: true points: type: array items: $ref: "#/components/schemas/v1MetricDataPoint" description: >- Time series data points for this specific tag combination. Chronologically ordered data points showing the metric value over time. readOnly: true description: >- A single time series for a specific combination of tag values. Each series represents one unique combination of the group_by dimensions, containing data points over time for that specific combination. required: - tags - points v1MetricDataPoint: type: object properties: start_time: type: string format: date-time description: >- The start time for this data point's interval. Represents the start of the interval for which the value is aggregated. readOnly: true value: type: number format: double description: |- The aggregated metric value for this interval. Result of applying the aggregation function to all matching records within this interval for this series' tag combination. readOnly: true window_label: type: string description: >- Human-readable label for the time window. Provides a formatted display name for the interval, formatted according to the interval granularity and the user's locale preferences. Examples: - HOUR: "Jan 15, 2025 10:00 AM", "2025-01-15 10:00" - DAY: "January 15, 2025", "2025-01-15" - WEEK: "Week of Jan 15, 2025", "2025-W03" - MONTH: "January 2025", "2025-01" readOnly: true description: |- A single data point in a metric time series. Represents an aggregated metric value at a specific point in time. required: - start_time - value - window_label v1AggregationFunction: type: string enum: - AGGREGATION_FUNCTION_UNSPECIFIED - AGGREGATION_FUNCTION_COUNT - AGGREGATION_FUNCTION_SUM - AGGREGATION_FUNCTION_AVG - AGGREGATION_FUNCTION_MIN - AGGREGATION_FUNCTION_MAX default: AGGREGATION_FUNCTION_UNSPECIFIED description: >- Aggregation function for metric values. Specifies how metric values should be aggregated within each interval. - AGGREGATION_FUNCTION_UNSPECIFIED: Unspecified aggregation. Defaults to COUNT. - AGGREGATION_FUNCTION_COUNT: Count of occurrences. - AGGREGATION_FUNCTION_SUM: Sum of values. - AGGREGATION_FUNCTION_AVG: Average of values. - AGGREGATION_FUNCTION_MIN: Minimum value. - AGGREGATION_FUNCTION_MAX: Maximum value. v1MetricInterval: type: string enum: - METRIC_INTERVAL_UNSPECIFIED - METRIC_INTERVAL_HOUR - METRIC_INTERVAL_DAY - METRIC_INTERVAL_WEEK - METRIC_INTERVAL_MONTH default: METRIC_INTERVAL_UNSPECIFIED description: >- Time interval for metric aggregation. Specifies the granularity at which metric data points are aggregated. The server may adjust the requested interval based on the time range or data availability. - METRIC_INTERVAL_UNSPECIFIED: Unspecified interval. Server will determine appropriate interval. - METRIC_INTERVAL_HOUR: Hourly aggregation. - METRIC_INTERVAL_DAY: Daily aggregation. - METRIC_INTERVAL_WEEK: Weekly aggregation. - METRIC_INTERVAL_MONTH: Monthly aggregation. v2SearchBookProceduresResponse: type: object properties: results: type: array items: $ref: "#/components/schemas/v2SearchBookProcedureMatch" title: Ranked list of matches for the given query title: Search results for book procedures v2SearchBookProcedureMatch: type: object properties: book_name: type: string title: Book name owning the procedure book_version: type: string title: Book version owning the procedure procedure: $ref: "#/components/schemas/v2BookProcedureDescriptor" score: type: number format: double title: Relevance score (higher is better) title: A match result for a searched procedure v2SearchBookProceduresRequest: type: object properties: query: type: string title: Free-text search query to match against procedure metadata and signatures top_k: type: integer format: int64 title: Maximum number of results to return max_distance: type: number format: float title: Maximum distance threshold for similarity matching title: Search for procedures across all available books v1ListEventsResponse: type: object properties: events: type: array items: $ref: "#/components/schemas/v1Event" description: The events in the conversation thread, ordered by creation time (newest first). 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 `ListEvents` to continue listing results. Will be empty when there are no more results. total_size: type: integer format: int32 description: >- The total number of events in the conversation thread across all pages. This count is not affected by page_size or page_token parameters. description: A response to a list events request. v1Event: type: object properties: name: type: string title: >- The full resource name of the event. Format: organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/{agent_id}/events/{event_id} state: $ref: "#/components/schemas/v1EventState" create_time: type: string format: date-time description: The timestamp when the event was created. readOnly: true update_time: type: string format: date-time description: The timestamp when the event was last updated. readOnly: true user_message: $ref: "#/components/schemas/v1UserMessage" agent_message: $ref: "#/components/schemas/v1AgentMessage" tool_call_request: $ref: "#/components/schemas/v1ToolCallRequest" tool_call_result: $ref: "#/components/schemas/v1ToolCallResult" thinking: $ref: "#/components/schemas/v1Thinking" system_message: $ref: "#/components/schemas/v1SystemMessage" completion_response: $ref: "#/components/schemas/v1CompletionResponse" exception: type: string title: >- An optional exception resource name that the event belongs to. Format: organizations/{organization_id}/workspaces/{workspace_id}/exceptions/{exception_id} description: >- An event in a run conversation thread about an exception. Events form a timeline of interactions between users, AI agents, and the system. v1ToolCallRequest: type: object properties: tool_call_id: type: string description: The unique identifier for the tool call. Used to match the tool call request with the tool call result. readOnly: true display_name: type: string description: The display name of the tool being called. readOnly: true input: type: string description: >- The input arguments passed to the tool. Contains arbitrary data in a tool-specific format that the agent generates for the tool call. Note: Clients should not parse this field. The length of this field may change during STATE_STREAMING as the agent constructs the tool call arguments. readOnly: true description: type: string description: A human-friendly description of the tool call. Generated by the tool call service. readOnly: true description: A tool call request made by the AI agent. v1Thinking: type: object properties: content: type: string description: The thinking content. CommonMark(GFM) formatted. readOnly: true description: Thinking or reasoning by the AI agent. v1SystemMessage: type: object properties: content: type: string description: The content of the system message. CommonMark(GFM) formatted. readOnly: true description: A system-generated message. v1CompletionResponse: type: object properties: content: type: string description: Final content if successful. error: type: string description: Error description if the request failed. description: Terminal completion for the agent workflow. v1EventState: type: string enum: - STATE_UNSPECIFIED - STATE_STREAMING - STATE_COMPLETE default: STATE_UNSPECIFIED description: >- The state of an event. - STATE_UNSPECIFIED: The state is not specified. This value is not used. - STATE_STREAMING: The event fields are being generated by the AI agent. event_data fields may have partial values. - STATE_COMPLETE: The event fields are done being generated. v1UserMessage: type: object properties: user: type: string title: |- The user who authored the message. Format: users/{user} content: type: string description: Simple text content. content_list: $ref: "#/components/schemas/v1InputContentList" description: A message from a user. v1InputContentList: type: object properties: items: type: array items: $ref: "#/components/schemas/v1InputContent" description: The list of input content items. description: A list of input content items (can contain text and/or binary content). required: - items v1InputContent: type: object properties: text: type: string description: Text content. file: $ref: "#/components/schemas/v1FileInputContent" description: InputContent represents a single input item that can be text or binary. v1FileInputContent: type: object properties: remote: type: string title: Reference to a remote file via URL or file path inline: $ref: "#/components/schemas/v1FileContent" description: FileInputContent represents a file that can be either stored inline or referenced remotely. v1FileContent: type: object properties: mime_type: type: string description: The MIME type of the file. content: type: string format: byte title: The raw binary content of the file filename: type: string title: The name of the file, including extension if applicable description: FileContent represents a file with its name and binary content. required: - mime_type - content v1AgentMessage: type: object properties: content: type: string description: The content of the message. CommonMark(GFM) formatted. readOnly: true description: A message from the AI agent. v1ToolCallResult: type: object properties: tool_call_id: type: string description: The unique identifier for the tool call. Used to match the tool call request with the tool call result. readOnly: true result: type: string description: >- The result of the tool call. Note: Clients should not parse this field. The length of this field may change during STATE_STREAMING as the agent constructs the tool call result. readOnly: true description: A tool call result returned by the tool. v2SetAutomationsForTriggerInstanceResponse: type: object properties: trigger_instance: $ref: "#/components/schemas/v2TriggerInstance" v2RetrieveWorkspaceTriggerInstancesResponse: type: object properties: trigger_instances: type: array items: $ref: "#/components/schemas/v2TriggerInstance" title: The trigger instances v1ExtractAutomationCodeConnectionsResponse: type: object properties: connections: type: array items: $ref: "#/components/schemas/v1CredentialInfo" description: >- List of connections found in the automation's SPy code. Includes both placeholder connections (without connection_id) and concrete connections (with connection_id). readOnly: true description: ExtractAutomationCodeConnectionsResponse returns connection information from the automation's SPy code. v1UpgradeAutomationConnectionsResponse: type: object properties: automation: $ref: "#/components/schemas/v1Automation" description: UpgradeAutomationConnectionsResponse returns the updated automation. v1OrganizationPreferences: type: object properties: name: type: string title: |- The resource name of the organization preferences. Format: `organizations/{organization}/preferences` support_team_access: type: boolean description: Support team access to workspaces in the organization for debugging issues. general: $ref: "#/components/schemas/v1GeneralPreferences" description: Represents organization-specific settings or preferences. v1InvokeAutomationResponse: type: object properties: run_id: type: string description: |- Unique identifier of the run created to execute the automation. Use this ID to track execution status and retrieve results. description: InvokeAutomationResponse returns the run ID for tracking the automation execution. v1AutomationRevision: type: object properties: name: type: string description: >- The name of the automation revision. Format: organizations/{organization}/workspaces/{workspace}/automations/{automation}/revisions/{revision} The revision ID is the semantic version string (e.g., "0.1", "1.0", "2.0"). snapshot: $ref: "#/components/schemas/v1Automation" create_time: type: string format: date-time description: Timestamp when this revision was created. readOnly: true alternate_ids: type: array items: type: string description: >- Other revision IDs that reference the same snapshot (e.g., "latest"). Per AIP-162, this allows aliases for revisions. readOnly: true input_diff: $ref: "#/components/schemas/v1AutomationInputDiff" description: >- AutomationRevision represents a historical revision (version) of an automation. Revisions are immutable snapshots created each time an automation is updated. Per AIP-162, this resource contains the complete state via a snapshot field. v1ListAutomationRevisionsResponse: type: object properties: revisions: type: array items: $ref: "#/components/schemas/v1AutomationRevision" description: |- The list of automation revisions for the current page. Revisions are ordered in reverse chronological order (newest first). next_page_token: type: string description: |- A token that can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no subsequent pages. description: ListAutomationRevisionsResponse returns a page of automation revisions and pagination information. v2RetrieveBooksResponse: type: object properties: books: type: array items: $ref: "#/components/schemas/v2BookDescriptor" title: All the books that satisfy the query next_page_token: type: string description: The token to use to retrieve the next page of books. v1CountConnectionUsageResponse: type: object properties: connection_counts: type: array items: $ref: "#/components/schemas/v1ConnectionAutomationCount" description: |- List of connection IDs with their corresponding automation counts. The order matches the order of connection_ids in the request. description: CountConnectionUsageResponse returns automation counts for each requested connection ID. v1ConnectionAutomationCount: type: object properties: connection_id: type: string description: The connection ID being counted. count: type: integer format: int32 description: |- The number of automations that use this connection. Includes both DRAFT and PUBLISHED automations by default. description: ConnectionAutomationCount represents the count of automations using a specific connection. 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. memberships: type: array items: $ref: "#/components/schemas/v1UserWorkspaceMembership" description: |- The same workspaces as `user_workspaces`, enriched with the current user's role(s) and join timestamp per workspace. Parallel to `user_workspaces` (same length / order); existing callers continue to use `user_workspaces` for N-1. Powers the "Organizations" section on the user profile page. description: Response message for listing workspaces for the current user within a specific organization. v2RemoveWorkspaceBookConnectionTriggerInstanceResponse: type: object v1GetExecutionOutputsResponse: type: object properties: outputs: type: object additionalProperties: $ref: "#/components/schemas/v1ExecutionOutput" description: >- Map of named output values set by the set_output() builtin function during execution. The key is the output name (string) and the value is the ExecutionOutput containing the value and type set by calling set_output(name, value). This map will be empty if no set_output() calls were made during execution. description: GetExecutionOutputsResponse contains the outputs from a completed execution. v1ExecutionOutput: type: object properties: value: $ref: "#/components/schemas/commonV1Value" type: $ref: "#/components/schemas/v1ValueType" description: ExecutionOutput represents an output value set by the set_output() builtin function during execution. v1TraceConnectionUsageResponse: type: object properties: automations: type: array items: $ref: "#/components/schemas/v1AutomationConnectionUsage" description: List of automations that use the specified connection, with their stages. description: TraceConnectionUsageResponse returns automations that use the specified connection. v1AutomationConnectionUsage: type: object properties: automation_id: type: string description: >- The automation ID that uses the connection. This is the automation ID portion only (e.g., the {automation} part of the resource name). stages: type: array items: $ref: "#/components/schemas/v1AutomationStage" description: >- The stages in which this automation uses the connection. Can include AUTOMATION_STAGE_DRAFT, AUTOMATION_STAGE_PUBLISHED, or both. description: >- AutomationConnectionUsage represents an automation that uses a specific connection, along with the stages (DRAFT, PUBLISHED, or both) where the connection is used. v1Invitation: type: object properties: name: type: string title: |- Resource name of the invitation. Format: organizations/{organization}/invitations/{invitation} organization_display_name: type: string description: The organization display name. workspace_id: type: string description: The workspace ID (not set if org-level invite). workspace_display_name: type: string description: The workspace display name (not set if org-level invite). roles: type: array items: type: string description: List of role resource names included in this invitation. is_accepted: type: boolean description: |- Whether the invitation has been accepted. Deprecated in favor of `status`. Kept for N-1 compatibility; when `status` is `INVITATION_STATUS_ACCEPTED`, this is also true. redirect_organization_id: type: string description: The organization ID to redirect to (set if invitation points to a different org). redirect_workspace_id: type: string description: The workspace ID to redirect to (set if invitation points to a different workspace). status: $ref: "#/components/schemas/v1InvitationStatus" direction: $ref: "#/components/schemas/v1InvitationDirection" create_time: type: string format: date-time description: |- Server-set creation timestamp from the underlying `user_invitations.created_at` column. Output-only. Surfaced so the admin-side Invitations table can show an "Invited on" column. readOnly: true description: An Invitation represents a pending invitation to join an organization or workspace. v1AutomationVisualization: type: object properties: name: type: string title: >- The resource name of the visualization. Format: organizations/{org}/workspaces/{ws}/automations/{automation}/visualization graph: $ref: "#/components/schemas/v1FlowGraph" automation_version: type: string description: >- The semantic version of the automation this visualization represents. Format: "major.0" (e.g., "1.0", "2.0", "3.0") - always a published version. This corresponds to the automation's published version at the time of generation. readOnly: true state: $ref: "#/components/schemas/v1VisualizationState" error_message: type: string description: |- Error message describing why generation failed. Only populated when state is VISUALIZATION_STATE_FAILED. readOnly: true description: >- AutomationVisualization represents a visual representation of an automation's execution flow. Visualizations are generated for published automation versions and stored as configurations for rendering in the UI. This is a singleton resource - each automation has exactly one visualization representing its latest published version. v1VisualizationState: type: string enum: - VISUALIZATION_STATE_UNSPECIFIED - VISUALIZATION_STATE_PENDING - VISUALIZATION_STATE_COMPLETED - VISUALIZATION_STATE_FAILED default: VISUALIZATION_STATE_UNSPECIFIED description: >- VisualizationState indicates the current state of visualization generation. - VISUALIZATION_STATE_UNSPECIFIED: Unspecified state. - VISUALIZATION_STATE_PENDING: Visualization generation is in progress. - VISUALIZATION_STATE_COMPLETED: Visualization generation completed successfully. - VISUALIZATION_STATE_FAILED: Visualization generation failed. v1FlowGraph: type: object properties: nodes: type: array items: $ref: "#/components/schemas/v1FlowNode" description: List of nodes representing steps in the automation flow. edges: type: array items: $ref: "#/components/schemas/v1FlowEdge" description: List of edges representing connections between nodes. description: >- FlowGraph represents the execution flow of an automation as a directed graph. The graph consists of nodes (representing steps) and edges (representing transitions). v1FlowEdge: type: object properties: source: type: string description: ID of the source node where the edge originates. target: type: string description: ID of the target node where the edge points. condition: type: string description: Optional condition label for the edge (e.g., "Yes", "No" for decision branches). description: FlowEdge represents a directed connection between two nodes. v1FlowNode: type: object properties: id: type: string description: Unique identifier for this node within the graph. label: type: string description: Human-readable label describing this step. type: $ref: "#/components/schemas/v1FlowNodeType" description: FlowNode represents a single step or decision point in the automation flow. v1FlowNodeType: type: string enum: - FLOW_NODE_TYPE_UNSPECIFIED - FLOW_NODE_TYPE_START - FLOW_NODE_TYPE_END - FLOW_NODE_TYPE_PROCESS - FLOW_NODE_TYPE_DECISION - FLOW_NODE_TYPE_INPUT - FLOW_NODE_TYPE_OUTPUT default: FLOW_NODE_TYPE_UNSPECIFIED description: >- FlowNodeType defines the different types of nodes in an automation flow. - FLOW_NODE_TYPE_UNSPECIFIED: Unspecified node type. - FLOW_NODE_TYPE_START: Start node - represents the beginning of the flow. - FLOW_NODE_TYPE_END: End node - represents the end of the flow. - FLOW_NODE_TYPE_PROCESS: Process node - represents a processing step. - FLOW_NODE_TYPE_DECISION: Decision node - represents a branching point (if-else conditions). - FLOW_NODE_TYPE_INPUT: Input node - represents an input action. - FLOW_NODE_TYPE_OUTPUT: Output node - represents an output action. v1ConnectionRemoval: type: object properties: connection_id: type: string description: |- The connection ID to remove. This connection ID must exist in the automation. connection_alias: type: string description: |- The alias of the connection to remove. This alias must match the connection being removed. description: ConnectionRemoval specifies a connection to remove from an automation. required: - connection_id - connection_alias v2SearchBookConceptsRequest: type: object properties: query: type: string title: Free-text search query to match against concept names and descriptions top_k: type: integer format: int64 title: Maximum number of results to return max_distance: type: number format: float title: Maximum distance threshold for similarity matching title: Search for concepts across all available books v1GuideEntry: type: object properties: name: type: string title: >- Resource name Format: organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/guideEntries/{guide_entry_id} content: type: string description: |- Markdown-formatted entry content Deprecated: Use resolution_steps and resolution_code instead. source_exception: type: string title: Exception that led to this entry's creation source_run: type: string title: Run where this entry was first created create_time: type: string format: date-time title: Creation timestamp readOnly: true update_time: type: string format: date-time title: Last update timestamp readOnly: true delete_time: type: string format: date-time description: >- The time when this guide entry was soft-deleted. If not set, the entry has not been deleted. Soft-deleted entries are not physically removed but marked as deleted. Always set the state to STATE_ARCHIVED whenever the entry is soft-deleted. readOnly: true title: type: string description: |- Title of the guide entry Marked as optional for backwards compatibility. Can be set when creating or updating the guide entry. automation: type: string title: >- The automation that the guide entry belongs to. Format: organizations/{organization}/workspaces/{workspace}/automations/{automation} readOnly: true root_cause: type: string description: |- Root cause analysis explaining why the exception occurred. This provides technical context about what caused the issue. Marked as optional for backwards compatibility. state: $ref: "#/components/schemas/v1GuideEntryState" version: type: string title: >- Semantic version of this specific version of the guide entry (format: major.minor). Incremented each time the guide entry is updated. Examples: "0.1", "1.0", "1.1", "2.0" readOnly: true resolution_steps: type: string description: >- Human-readable explanation of the resolution action and steps. GitHub Flavored Markdown (GFM) formatted. Resolution Field Guidelines: - At least one of resolution_steps, resolution_code, or resolution_notes should be present for the guide entry to be useful. Entries with none of these fields are considered incomplete. - These fields are complementary and can be used together: - resolution_steps: The primary resolution instructions - resolution_code: Supporting code examples - resolution_notes: Additional context or caveats resolution_code: type: string description: >- Example code illustrating how this type of exception was resolved. Serves as a reference when handling similar exceptions in future runs. May require adaptation based on specific context and should not be applied verbatim. resolution_notes: type: string description: |- Additional notes, caveats, or context about the resolution. GitHub Flavored Markdown (GFM) formatted. Use for edge cases, warnings, or supplementary information. kind: type: string description: |- Free-form category used to organize guide entries by origin or type. Caller-provided; the server defaults this to "resolution" when left empty. "resolution" entries are exception resolutions (the historical behavior and the only kind agents produce while resolving an exception). Other values (e.g. "learning") denote general, possibly human-authored guidance that may not be tied to any exception. approver: type: string description: |- Acting user who approved the current version of this guide entry via TransitionGuideEntryState(ACTION_APPROVE). Format: users/{user} Empty when the entry has never been approved. readOnly: true reverted_from: type: string description: |- Semantic version (format: major.minor) this version was reverted from, when this version was produced by RevertGuideEntry. Empty when the version was produced by a create or an ordinary update rather than a revert. Examples: "0.3", "1.0". readOnly: true title: A troubleshooting guide entry for an automation v1GuideEntryState: type: string enum: - STATE_UNSPECIFIED - STATE_PENDING_APPROVAL - STATE_APPROVED - STATE_REJECTED - STATE_ARCHIVED default: STATE_UNSPECIFIED description: |- The state of a guide entry. - STATE_UNSPECIFIED: The state is not specified. - STATE_PENDING_APPROVAL: The guide entry is pending approval. - STATE_APPROVED: The guide entry is approved. - STATE_REJECTED: The guide entry is rejected. - STATE_ARCHIVED: The guide entry is archived. dashboardsConfigureAutomationEstimatesResponse: type: object properties: automation_estimates: type: array items: $ref: "#/components/schemas/dashboardsAutomationEstimate" description: The list of configured automation estimates. readOnly: true description: |- Response message for ConfigureAutomationEstimates method. Returns the configured automation estimates for the workspace. v1AddAutomationConnectionsResponse: type: object properties: automation: $ref: "#/components/schemas/v1Automation" description: AddAutomationConnectionsResponse returns the updated automation. v2RetrieveDiscoverablesResponse: type: object properties: discoverables: type: array items: $ref: "#/components/schemas/v2Discoverable" title: The retrieved Discoverables title: The response to a get discoverables request v2Discoverable: type: object properties: name: type: string title: The name of the discoverable description: type: string title: The description of the discoverable v1ListExceptionGroupsResponse: type: object properties: groups: type: array items: $ref: "#/components/schemas/v1ExceptionGroup" description: Available exception groups and their metadata. next_page_token: type: string description: |- Token to retrieve the next page of results. Empty when there are no more results. description: Response containing available exception groups. v1ListOrganizationRolesResponse: type: object properties: roles: type: array items: $ref: "#/components/schemas/v1Role" description: The list of roles 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 ListOrganizationRoles to get the next page of results. description: Response message for ListOrganizationRoles. v1UploadFileResponse: type: object properties: metadata: $ref: "#/components/schemas/v1FileMetadata" title: >- Response after uploading a file For HTTP/REST: Returns JSON with metadata HTTP Status: 201 Created with Location header pointing to the created resource v1FileMetadata: type: object properties: name: type: string title: The resource name of the file (server-generated) readOnly: true filename: type: string title: Filename of the file (e.g., "document.pdf") mime_type: type: string title: MIME type of the file (server-detected for security) readOnly: true size_bytes: type: string format: int64 title: Size of the file in bytes (server-calculated) readOnly: true create_time: type: string format: date-time title: Timestamp when the file was created readOnly: true sha256_hash: type: string description: |- SHA-256 hash of the file content, lowercase hex-encoded (64 chars). Computed by the server at upload time over the raw bytes. Follows the Cloud Storage `md5_hash` / `crc32c` naming pattern (see https://cloud.google.com/storage/docs/hashes-etags). readOnly: true update_time: type: string format: date-time description: |- Timestamp when the file's content was last replaced. Unset if the content has never been replaced. readOnly: true title: File metadata resource in the Bishop system required: - filename v2RetrieveBookConnectionsResponse: type: object properties: book_connections: type: array items: $ref: "#/components/schemas/v2BookConnectionDescriptor" title: The list of book connections next_page_token: type: string description: The token to use to retrieve the next page of connections. v2SearchBookConceptsResponse: type: object properties: results: type: array items: $ref: "#/components/schemas/v2SearchBookConceptMatch" title: Ranked list of concept matches for the given query title: Search results for book concepts v2SearchBookConceptMatch: type: object properties: book_name: type: string title: Book name containing the concept book_version: type: string title: Book version containing the concept concept: $ref: "#/components/schemas/v2ConceptDescriptor" score: type: number format: double title: Relevance score (higher is better) title: A match result for a searched concept v2DiscoverWorkspaceBookConnectionProceduresResponse: type: object title: A response that is sent to reply to a library discovery request v1DeleteWorkspaceConnectionResponse: type: object properties: affected_automations: type: array items: $ref: "#/components/schemas/v1AffectedAutomation" description: >- List of draft automations that were affected by the deletion. These automations have connection references that are now unresolved. Empty if no draft automations were using the connection. readOnly: true description: DeleteWorkspaceConnectionResponse returns information about affected automations. v1AffectedAutomation: type: object properties: automation_id: type: string description: The automation ID (the {automation} segment of the resource name). readOnly: true display_name: type: string description: The human-readable display name of the automation. readOnly: true description: AffectedAutomation describes a draft automation affected by connection deletion. v1ListGuideEntriesResponse: type: object properties: guide_entries: type: array items: $ref: "#/components/schemas/v1GuideEntry" title: The guide entries 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 `ListGuideEntries` to continue listing results. Will be empty when there are no more results. total_size: type: integer format: int32 description: >- The total number of guide entries across all pages. This count respects the show_deleted parameter but is not affected by page_size or page_token. title: Response to a list guide entries request apiHttpBody: type: object properties: content_type: type: string description: The HTTP Content-Type header value specifying the content type of the body. data: type: string format: byte description: The HTTP request/response body as raw binary. extensions: type: array items: $ref: "#/components/schemas/protobufAny" description: >- Application specific response metadata. Must be set in the first response for streaming APIs. description: >- Message that represents an arbitrary HTTP body. It should only be used for payload formats that can't be represented as JSON, such as raw binary or an HTML page. This message can be used both in streaming and non-streaming API methods in the request as well as the response. It can be used as a top-level request field, which is convenient if one wants to extract parameters from either the URL or HTTP template into the request fields and also want access to the raw HTTP body. Example: message GetResourceRequest { // A unique request id. string request_id = 1; // The raw HTTP body is bound to this field. google.api.HttpBody http_body = 2; } service ResourceService { rpc GetResource(GetResourceRequest) returns (google.api.HttpBody); rpc UpdateResource(google.api.HttpBody) returns (google.protobuf.Empty); } Example with streaming methods: service CaldavService { rpc GetCalendar(stream google.api.HttpBody) returns (stream google.api.HttpBody); rpc UpdateCalendar(stream google.api.HttpBody) returns (stream google.api.HttpBody); } Use of this type only changes how the request and response bodies are handled, all other features will continue to work unchanged. dashboardsQueryInsightsResponse: type: object properties: value_insight: $ref: "#/components/schemas/dashboardsValueInsight" run_insight: $ref: "#/components/schemas/dashboardsRunInsight" completion_insight: $ref: "#/components/schemas/dashboardsCompletionInsight" awaiting_guidance_insight: $ref: "#/components/schemas/dashboardsAwaitingGuidanceInsight" description: >- Response message for QueryInsights method. Contains aggregated analytics insights across value, runs, and completions. dashboardsRunInsight: type: object properties: total_runs_count: type: string format: int64 description: Total number of runs across all automations and workspaces. readOnly: true insights_per_automation_per_workspace: type: object additionalProperties: $ref: "#/components/schemas/dashboardsAutomationRunInsightList" title: >- Run insights grouped per automation per workspace. Key: workspace_id (format: organizations/{org}/workspaces/{workspace}) readOnly: true insights_per_period_per_workspace: type: object additionalProperties: $ref: "#/components/schemas/dashboardsCumulativeRunInsightList" title: >- Run insights grouped per time period per workspace. Key: workspace_id (format: organizations/{org}/workspaces/{workspace}) readOnly: true trend: $ref: "#/components/schemas/dashboardsTrend" description: RunInsight contains aggregated runCount metrics. dashboardsAutomationRunInsightList: type: object properties: values: type: array items: $ref: "#/components/schemas/dashboardsAutomationRunInsight" description: List of run insights per automation. readOnly: true description: AutomationRunInsightList contains run insights for automations within a workspace. dashboardsAutomationRunInsight: type: object properties: automation_id: type: string title: >- The automation ID. Format: organizations/{organization}/workspaces/{workspace}/automations/{automation} readOnly: true display_name: type: string description: The display name of the automation. readOnly: true runs_count: type: string format: int64 description: Number of runs for this automation. readOnly: true description: AutomationRunInsight contains run count metrics for a specific automation. dashboardsTrend: type: object properties: percent_change: type: number format: double description: >- The percentage change compared to the previous time window. Positive values indicate increase, negative values indicate decrease. readOnly: true comparison_window: type: string description: The label of the time window being compared against (e.g., "Last Week", "Previous Month"). readOnly: true description: Trend represents a percentage change compared to a previous time window. dashboardsCumulativeRunInsightList: type: object properties: values: type: array items: $ref: "#/components/schemas/dashboardsCumulativeRunInsight" description: List of run insights per time period. readOnly: true description: CumulativeRunInsightList contains run insights grouped per time period within a workspace. dashboardsCumulativeRunInsight: type: object properties: window_label: type: string description: The display label of the time period (e.g., "Week 1", "January 2025"). readOnly: true runs_count: type: string format: int64 description: Number of runs during this period. readOnly: true description: CumulativeRunInsight contains run count metrics for a specific time period. dashboardsCompletionInsight: type: object properties: total_percent_completions: type: number format: double description: Overall completion percentage across all runs. readOnly: true completions_per_period: type: array items: $ref: "#/components/schemas/dashboardsCumulativeCompletionInsight" description: Completion insights grouped per time period. readOnly: true trend: $ref: "#/components/schemas/dashboardsTrend" stp: type: number format: double description: Straight-through processing rate. readOnly: true description: CompletionInsight contains completion rate metrics. dashboardsCumulativeCompletionInsight: type: object properties: window_label: type: string description: The display label of the time period (e.g., "Week 1", "January 2025"). readOnly: true auto_completed_count: type: string format: int64 description: Number of runs that completed automatically without manual intervention. readOnly: true manually_resolved_count: type: string format: int64 description: Number of runs that required manual resolution. readOnly: true total_runs_count: type: string format: int64 description: |- Total number of runs started in this time period. Can be used to derive incomplete runs: total_runs_count - auto_completed_count - manually_resolved_count. readOnly: true description: CumulativeCompletionInsight contains completion metrics for a specific time period. dashboardsAwaitingGuidanceInsight: type: object properties: total_runs_awaiting_guidance: type: string format: int64 description: Total number of runs awaiting guidance. readOnly: true runs_per_period: type: array items: $ref: "#/components/schemas/dashboardsRunsAwaitingGuidanceByPeriod" description: Runs awaiting guidance grouped per time period. readOnly: true description: AwaitingGuidanceInsight contains metrics for runs awaiting guidance. dashboardsRunsAwaitingGuidanceByPeriod: type: object properties: window_label: type: string description: The display label of the time period (e.g., "January 2026", "December 2025"). readOnly: true runs_awaiting_guidance: type: string format: int64 description: Number of runs created in this period that are awaiting guidance. readOnly: true description: RunsAwaitingGuidanceByPeriod contains runs awaiting guidance for a specific time period. dashboardsValueInsight: type: object properties: total_money_saved_usd: type: string description: Total money saved across all automations and workspaces in USD. readOnly: true total_time_saved_secs: type: string format: int64 description: Total time saved across all automations and workspaces in seconds. readOnly: true insights_per_automation_per_workspace: type: object additionalProperties: $ref: "#/components/schemas/dashboardsAutomationValueInsightList" title: >- Value insights grouped per automation per workspace. Key: workspace_id (format: organizations/{org}/workspaces/{workspace}) readOnly: true insights_per_period_per_workspace: type: object additionalProperties: $ref: "#/components/schemas/dashboardsCumulativeValueInsightList" title: >- Value insights grouped per time period per workspace. Key: workspace_id (format: organizations/{org}/workspaces/{workspace}) readOnly: true description: ValueInsight contains aggregated value metrics (cost and time savings). dashboardsCumulativeValueInsightList: type: object properties: values: type: array items: $ref: "#/components/schemas/dashboardsCumulativeValueInsight" description: List of value insights per time period. readOnly: true description: CumulativeValueInsightList contains value insights grouped per time period within a workspace. dashboardsCumulativeValueInsight: type: object properties: window_label: type: string description: The display label of the time period (e.g., "Week 1", "January 2025"). readOnly: true time_saved_secs: type: string format: int64 description: Time saved during this period in seconds. readOnly: true money_saved_usd: type: string description: Money saved during this period in USD. readOnly: true description: CumulativeValueInsight contains value metrics for a specific time period. dashboardsAutomationValueInsightList: type: object properties: values: type: array items: $ref: "#/components/schemas/dashboardsAutomationValueInsight" description: List of value insights per automation. readOnly: true description: AutomationValueInsightList contains value insights for automations within a workspace. dashboardsAutomationValueInsight: type: object properties: automation_id: type: string title: >- The automation ID. Format: organizations/{organization}/workspaces/{workspace}/automations/{automation} readOnly: true display_name: type: string description: The display name of the automation. readOnly: true time_saved_secs: type: string format: int64 description: Time saved by this automation in seconds. readOnly: true money_saved_usd: type: string description: Money saved by this automation in USD. readOnly: true description: AutomationValueInsight contains value metrics for a specific automation. v1QueryDailyRunAggregatesResponse: type: object properties: daily_run_aggregates: type: array items: $ref: "#/components/schemas/v1DailyRunAggregateEntry" description: List of daily run statistics entries. readOnly: true description: |- Response message for QueryDailyRunAggregates method. Contains daily run statistics as a list of entries. v1DailyRunAggregateEntry: type: object properties: date: type: string description: >- The date for this entry. Format: YYYY-MM-DD (e.g., "2024-01-01"). Using google.type.Date causing issue while transcoding to json. readOnly: true stats: $ref: "#/components/schemas/v1DailyRunAggregate" description: |- Entry for daily run statistics. Contains the date and run counts for that date. v1DailyRunAggregate: type: object properties: total_runs: type: integer format: int32 description: The total number of runs created on this date. readOnly: true description: |- Stats for a single day. Contains run counts for all runs in the workspace on that date. v1GenerateDownloadUrlResponse: type: object properties: download_uri: type: string title: Presigned download URI title: Response with presigned download URL 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. v2RetrieveTagsResponse: type: object properties: tags: type: array items: type: string title: Tags title: Response to retrieve tags v1SwitchAutomationConnectionsResponse: type: object properties: automation: $ref: "#/components/schemas/v1Automation" description: SwitchAutomationConnectionsResponse returns the updated automation. v1ListRunsResponse: type: object properties: runs: type: array items: $ref: "#/components/schemas/v1Run" description: >- The list of runs matching the request criteria. May be empty if no runs are found or if the page is beyond available results. readOnly: true next_page_token: type: string description: |- A token that can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no subsequent pages. readOnly: true content_matches: type: object additionalProperties: $ref: "#/components/schemas/v1RunContentMatch" description: |- For each run on this page that matched the filter's search term inside the text of its files, which files matched and where, so a client can show why the run matched when none of its values contain the term, for example "matched in invoice.pdf, page 3". Key: run name (format: organizations/{organization}/workspaces/{workspace}/automations/{automation}/runs/{run}), the name of one of the runs in runs. Filled only when the filter has a search term, and only terms of at least 3 characters are matched against file text. A run that matched on its values alone has no entry, and there are none when the organization opted out of content search. Entries name files and locations, never the matched text. readOnly: true description: |- Response message for ListRuns method. Contains a paginated list of runs and pagination metadata. v1ListExceptionsResponse: type: object properties: exceptions: type: array items: $ref: "#/components/schemas/v1Exception" description: The exceptions. 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 `ListExceptions` to continue listing results. Will be empty when there are no more results. total_size: type: integer format: int32 description: >- The total number of exceptions that match the given filter across all pages. This count is not affected by page_size or page_token parameters. description: A response to a list exceptions request. v1ListOrganizationUserInvitesResponse: 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 ListOrganizationUserInvites to get the next page of results. description: Response message for ListOrganizationUserInvites. v1RemoveAutomationConnectionsResponse: type: object properties: automation: $ref: "#/components/schemas/v1Automation" description: RemoveAutomationConnectionsResponse returns the updated automation. SearchWorkspaceBookConceptsBody: type: object properties: query: type: string title: Free-text search query to match against concept names and descriptions top_k: type: integer format: int64 title: Maximum number of results to return max_distance: type: number format: float title: Maximum distance threshold for similarity matching title: Search for concepts across all available books in a workspace AddWorkspaceBookConnectionTriggerInstanceBody: type: object properties: trigger_id: type: string title: The name of the trigger configuration: type: object additionalProperties: $ref: "#/components/schemas/bdkV2Value" title: Configuration parameters for the trigger filter_expression: $ref: "#/components/schemas/v2Expression" name: type: string title: The name of the trigger instance GenerateUploadUrlBody: type: object properties: expire_duration: type: string title: Optional expiration duration description: If no expiration duration is provided, the default is 1 hour. title: Request to generate presigned upload URL UpgradeWorkspaceBookConnectionBody: type: object properties: new_book_version: type: string title: The new version to upgrade book to SearchWorkspaceBookProceduresBody: type: object properties: query: type: string title: Free-text search query to match against procedure metadata and signatures top_k: type: integer format: int64 title: Maximum number of results to return max_distance: type: number format: float title: Maximum distance threshold for similarity matching filter: type: string description: |- Evaluated against the labels on the source BookConnection. Only `labels.` fields are supported, with `=`/`!=` comparators, AND/OR/NOT composition, and string or boolean values. Example: `labels.draft_connection = "true"`. title: |- AIP-160 Filtering https://google.aip.dev/160 title: Search for procedures across all available books in a workspace SetAutomationsForTriggerInstanceBody: type: object properties: automation_ids: type: array items: type: string title: The identifiers of the automations to attach to the trigger instance connection_id: type: string title: The id of the book connection AddAutomationConnectionsBody: type: object properties: connections: type: array items: $ref: "#/components/schemas/v1CredentialInfo" description: >- List of connections to add. All additions are performed atomically: either all succeed or all fail. The automation version is incremented once for all additions. Each connection must be unique within the list. If duplicate connections appear, the request will fail with INVALID_ARGUMENT. description: AddAutomationConnectionsRequest specifies which connections to add to a draft automation. required: - connections SearchWorkspaceBooksBody: type: object properties: query: type: string title: Free-text search query to match against book name, version, tags, or descriptions top_k: type: integer format: int64 title: Maximum number of results to return max_distance: type: number format: float title: Maximum distance threshold for similarity matching title: Search for books across the library in a workspace SwitchAutomationConnectionsBody: type: object properties: switches: type: array items: $ref: "#/components/schemas/v1ConnectionReplacement" description: >- List of connections to switch. All switches are performed atomically: either all succeed or all fail. The automation version is incremented once for all switches. Each old_connection_id must be unique within the list. If the same old_connection_id appears multiple times, the request will fail with INVALID_ARGUMENT. description: SwitchAutomationConnectionsRequest specifies which connections to switch in a draft automation. required: - switches UpdateWorkspaceBookConnectionBody: type: object properties: connection_name: type: string title: The connection name authentication: $ref: "#/components/schemas/v2Authentication" config_map: type: object additionalProperties: $ref: "#/components/schemas/bdkV2Value" title: Input config labels: type: array items: $ref: "#/components/schemas/bdkV2Label" title: Labels associated with the connection oauth_flow: $ref: "#/components/schemas/v2OAuthFlow" title: The book connection to update SetDiscoveredBody: type: object properties: what: type: array items: type: string title: What should be discovered DisableAutomationScheduleBody: type: object description: DisableAutomationScheduleRequest is the request to disable a schedule (pause without deleting). ContinueRunBody: type: object description: |- Request message for ContinueRun method. Specifies which run to resume by its unique identifier. TraceConnectionUsageBody: type: object properties: connection_id: type: string description: |- The connection ID to trace usage for. Returns all automations that use this connection. description: TraceConnectionUsageRequest specifies which connection to trace usage for. required: - connection_id InvokeAutomationBody: type: object properties: inputs: type: object additionalProperties: $ref: "#/components/schemas/commonV1Value" description: |- Input values to pass to the automation execution. Keys are input parameter names, values are the corresponding values. stage: $ref: "#/components/schemas/v1AutomationStage" enable_astral_on_rain: type: boolean description: |- When true and the automation is Quill2 kind, enables Astral-on-Rain exception handling for this invocation. Has no effect for non-Quill2 automations. idempotency_key: type: string description: |- Client-supplied UUID4 idempotency token for InvokeAutomation. Threaded to Jeeves CreateRun as request_id so retries with the same key return the existing run instead of spawning a duplicate. description: InvokeAutomationRequest contains the automation ID and inputs needed to execute an automation. required: - stage SearchWorkspaceBookConnectionProceduresBody: type: object properties: query: type: string title: Free-text search query to match against procedure metadata and signatures top_k: type: integer format: int64 title: Maximum number of results to return max_distance: type: number format: float title: Maximum distance threshold for similarity matching title: Search for procedures across all available books in a connection PauseRunBody: type: object properties: reason: type: string description: The reason for pausing the run. description: |- Request message for PauseRun method. Specifies which run to pause by its unique identifier. required: - reason UpgradeAutomationConnectionsBody: type: object properties: upgrades: type: array items: $ref: "#/components/schemas/v1ConnectionReplacement" description: >- List of connections to upgrade. All upgrades are performed atomically: either all succeed or all fail. The automation version is incremented once for all upgrades. Each old_connection_id must be unique within the list. If the same old_connection_id appears multiple times, the request will fail with INVALID_ARGUMENT. description: UpgradeAutomationConnectionsRequest specifies which connections to upgrade in a draft automation. required: - upgrades GenerateDownloadUrlBody: type: object properties: expire_duration: type: string title: Optional expiration duration format: $ref: "#/components/schemas/v1DownloadFormat" description: If no expiration duration is provided, the default is 1 hour. title: Request to generate presigned download URL EnableAutomationScheduleBody: type: object description: EnableAutomationScheduleRequest is the request to enable a previously disabled schedule. AddWorkspaceBookConnectionBody: type: object properties: connection_name: type: string title: The connection name authentication: $ref: "#/components/schemas/v2Authentication" config_map: type: object additionalProperties: $ref: "#/components/schemas/bdkV2Value" title: Configuration for the connection labels: type: array items: $ref: "#/components/schemas/bdkV2Label" title: Labels associated with the connection oauth_flow: $ref: "#/components/schemas/v2OAuthFlow" associated_remote_connection_id: type: string title: The id of the associated remote connection auto_upgrade: type: boolean description: |- Whether the controller may automatically upgrade this connection to newer non-breaking (same major) versions of the book. Optional: when unset the connection is created with auto-upgrade enabled. Set to false to pin the connection to book_version. title: The book connection to add CountConnectionUsageBody: type: object properties: connection_ids: type: array items: type: string description: |- List of connection IDs to count automation usage for. Each connection ID will have a corresponding entry in the response. description: CountConnectionUsageRequest specifies connection IDs to count automation usage for. required: - connection_ids RemoveAutomationConnectionsBody: type: object properties: removals: type: array items: $ref: "#/components/schemas/v1ConnectionRemoval" description: >- List of connections to remove. All removals are performed atomically: either all succeed or all fail. The automation version is incremented once for all removals. Each connection (identified by connection_id and connection_alias) must be unique within the list. If the same connection appears multiple times, the request will fail with INVALID_ARGUMENT. For each connection, the corresponding entry in automation.connections will be removed and code references will be replaced with placeholders (kognitos.connection_name.{book}). description: RemoveAutomationConnectionsRequest specifies which connections to remove from a draft automation. required: - removals 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 ConfigureAutomationEstimatesBody: type: object properties: automation_estimates: type: array items: $ref: "#/components/schemas/dashboardsAutomationEstimate" description: The list of automation estimates to configure. description: >- Request message for ConfigureAutomationEstimates method. Configures the estimated cost and time savings for automations within a workspace. required: - automation_estimates agentsV1SendMessageResponse: type: object properties: ok: type: boolean description: Whether the message was accepted. description: Response from sending a message. agentsV1StopResponse: type: object properties: stopped: type: boolean description: |- True if a generation was active and has been stopped. False if no generation was in progress for the thread. description: Response for stopping an in-progress generation. agentsV1CreateAgentResponse: type: object properties: id: type: string description: The newly created agent's unique identifier. name: type: string description: The agent's display name. version: type: string format: uint64 description: The version number of the newly created agent (always 1 for new agents). description: Response message for CreateAgent. agentsThreadServiceMarkStepBody: type: object properties: status: $ref: "#/components/schemas/agentsV1StepStatus" failure_reason: type: string description: Optional reason for failure (only used when status is STEP_STATUS_FAILED). description: Request to mark a step's status in a thread's plan. agentsV1ImportAgentResponse: type: object properties: agent_id: type: string description: The imported agent's unique identifier. agent_name: type: string description: The imported agent's display name. saved_sub_agent_ids: type: array items: type: string description: IDs of sub-agents that were saved to the store as part of the import. warnings: type: array items: type: string description: Non-fatal warnings encountered during import. version: type: string format: uint64 description: |- Resulting latest version of the imported root agent. When the agent already existed and the spec changed, this is the newly created version; when the spec was identical, it is the unchanged latest version (and a warning is included). description: Response message for ImportAgent. agentsThreadServiceSendMessageBody: type: object properties: message: $ref: "#/components/schemas/agentsV1UserMessage" interrupt_reply: $ref: "#/components/schemas/agentsV1InterruptReply" tool_approval_reply: $ref: "#/components/schemas/agentsV1ToolApprovalReply" description: Request to send a message to a thread. agentsAgentServiceRestoreAgentVersionBody: type: object properties: {} description: Request to restore a previous agent version as a new version at the head. agentsV1ArtifactContentResponse: type: object properties: artifact: $ref: "#/components/schemas/agentsV1Artifact" data: type: string format: byte description: The raw content bytes. description: Response for GetArtifactContent. agentsThreadServiceWakeBody: type: object properties: {} description: |- Request to wake a thread that is currently sleeping. Atomically ends the pending sleep with `interrupted_by_user = true`, cancels the scheduled wake task, and triggers a new generation so the LLM observes the early return in its rebuilt history. No-op when the thread is not currently sleeping; this is a fall-through to a Reminder-triggered generation in that case. agentsV1InterruptReply: type: object properties: interrupt_id: type: string description: The interrupt_id from the Interrupt event. answers: type: array items: $ref: "#/components/schemas/agentsV1QuestionAnswer" description: Answers to the questions. description: User's reply to an interrupt (request type). agentsThreadServiceStopBody: type: object properties: {} description: Request to stop an in-progress generation in a thread. agentsV1Thread: type: object properties: thread_id: type: string description: The unique thread identifier (auto-generated). title: type: string description: Optional human-readable title for the thread. description: type: string description: Optional description of the thread's purpose or context. created_at: type: string format: date-time description: When the thread was created. variables: type: object additionalProperties: type: string description: |- Thread variables for configuration resolution. Variables are set at creation time and are immutable. feedback: type: object additionalProperties: $ref: "#/components/schemas/agentsV1FeedbackType" description: |- User feedback for generation responses (keyed by generation_id). Used for analytics and UI, not visible to the LLM. metadata: type: object additionalProperties: type: string description: Arbitrary key-value metadata attached by the thread creator. event_count: type: string format: int64 description: Number of events in this thread. agent_version: type: string format: uint64 description: |- Agent version this thread is pinned to. The thread resolves its agent template against this specific version for the rest of its life. Moving a thread to a newer version is an explicit user action (UpgradeThread / Deploy re-pin), never a side effect of an agent save. Zero is the sentinel for threads created without a pin (e.g. before the agent_version column existed); the server resolves such threads as current head. updated_at: type: string format: date-time description: |- When the thread was last modified. Bumped on any state change: event append, metadata edit, feedback edit, variable extension via UpgradeThread, plan/memory/scratchpad writes, etc. ListThreads returns threads sorted by this field in descending order (most recently active first); pre-existing threads from before this field was added fall back to created_at. created_by: $ref: "#/components/schemas/agentsV1PrincipalRef" updated_by: $ref: "#/components/schemas/agentsV1PrincipalRef" origin: $ref: "#/components/schemas/agentsV1ThreadOrigin" status: $ref: "#/components/schemas/agentsV1ThreadStatus" status_updated_at: type: string format: date-time description: When the thread entered its current status. plan_active: type: boolean description: Whether a plan is active on the thread (orthogonal to status). agent_id: type: string description: |- The owning agent's id. Populated by cross-agent listings (ListAllThreads); empty for single-agent listings where the agent is implied by the request. agent_name: type: string description: |- The owning agent's display name. Populated by cross-agent listings; empty otherwise. cost: $ref: "#/components/schemas/agentsV1Cost" stats: $ref: "#/components/schemas/agentsV1ThreadStats" dehydration: $ref: "#/components/schemas/agentsV1DehydrationState" description: A conversation thread with an AI agent. agentsV1DuplicateAgentResponse: type: object properties: id: type: string description: The newly created agent's unique identifier. name: type: string description: The agent's display name. description: Response message for DuplicateAgent. agentsV1DiscardArtifactsResponse: type: object properties: discarded_count: type: integer format: int64 description: Number of artifacts discarded. additions: type: integer format: int64 description: Number of additions discarded. modifications: type: integer format: int64 description: Number of modifications discarded. deletions: type: integer format: int64 description: Number of deletions discarded. description: Response for DiscardArtifacts. agentsV1DeleteEventResponse: type: object properties: from_event_id: type: string format: uint64 to_event_id: type: string format: uint64 agentsV1SendToolCallResponse: type: object properties: ok: type: boolean description: Whether the call was accepted (validated and queued for execution). tool_call_id: type: string description: |- The minted tool_call_id. Clients can correlate against the resulting ToolCallStart / ToolResult events on the thread event stream. description: Response from injecting a tool call. agentsThreadServiceResetEventsBody: type: object properties: {} description: Request message for ResetEvents (clear all events and feedback from a thread). agentsV1StartCompactionResponse: type: object properties: compact_id: type: string description: The unique ID assigned to this compaction operation. description: Response for starting context compaction. agentsV1ImportAgentRequest: type: object properties: format: type: string description: Required. The import format kind (e.g., "yaml", "kubernetes"). data: type: string format: byte description: Required. Raw file content to import. config: type: object description: Format-specific configuration options. description: Request message for ImportAgent. required: - format - data agentsToolCatalogServiceCreateToolSourceBody: type: object properties: type: type: string description: Required. The tool source type (e.g., "rust", "grpc"). config: type: object description: |- Required. Configuration for the tool source. Keys and values depend on the type's config_fields. source_id: type: string description: |- Optional. The id to give the source, instead of a generated one. For client-declared capabilities, which name their source `client.` so that toggling one off can address it and toggling it on twice cannot produce two copies. Rejected when a source already holds the id, and rejected if it contains ':' — that character is reserved for custom methods in resource paths, so an id carrying one could never be addressed again. description: Request message for CreateToolSource. required: - type - config agentsV1ToolEnablement: type: object properties: source_id: type: string description: The tool source this enablement applies to. readOnly: true tools: type: array items: $ref: "#/components/schemas/agentsV1Tool" description: |- Enabled tools with their descriptor snapshots. Order is not significant. description: |- Which tools from one source are enabled for the agent or thread. The source describes what tools exist; the enablement describes what is turned on. An absent enablement (or an empty `tools` list) means no tools from that source are exposed to the LLM. agentsAgentServiceDuplicateAgentBody: type: object properties: name: type: string description: |- Optional name for the copy. Fails with ALREADY_EXISTS when the name's derived ID is taken. When omitted, defaults to "Copy of {source_name}", numbered "Copy of {source_name} (2)", "(3)", ... until the ID is free. description: Request message for DuplicateAgent. agentsV1CreateAgentRequest: type: object properties: name: type: string description: |- Required. The display name for the new agent. The agent ID will be derived from this name (lowercase, dashed). description: |- Request to create a new agent. The agent is created with an empty template (no generator, no tools, no memory blocks, no variables). The agent is queryable but not runnable until a thread sets the desired configuration as overrides and deploys to produce a new version. agentsV1SendToolResultResponse: type: object properties: ok: type: boolean description: Whether the tool result was accepted and generation resumed. description: Response from sending a tool result. agentsV1ThreadStats: type: object properties: model: type: string description: |- The latest model the thread generated on (e.g. "claude-opus-4-8"). Absent when the thread has never generated. readOnly: true provider: type: string description: |- Generator kind of the latest model (e.g. "anthropic"), used to resolve the model badge glyph. Absent when the thread has never generated. readOnly: true total_tokens: type: string format: uint64 description: Total tokens across every billing class of the thread's usage. readOnly: true tool_calls: type: string format: uint64 description: Tool calls the thread has issued. readOnly: true errors: type: string format: uint64 description: |- Thread-level failures: terminal generation failures and plan executions that did not complete. readOnly: true recent_activity: type: array items: type: integer format: int64 description: |- Recent per-generation total token counts, oldest first, bounded to the most recent generations. Rendered as the activity sparkline. readOnly: true description: |- Display aggregates for a thread, projected from its usage aggregate at listing time. Drives the monitoring-style thread card: the model badge, the tool/error/token strip, and the activity sparkline. agentsThreadServiceRestoreEventBody: type: object properties: event_id: type: string format: uint64 description: |- Restores a previously deleted event and its entire associated turn. The event_id must refer to the InputText event that was previously deleted. All events in the turn are restored. Returns NOT_FOUND if no deleted turn starts at the given event_id. agentsV1Plan: type: object properties: name: type: string description: Name of the plan. description: type: string description: Description of the plan. active: type: boolean description: Whether the plan is currently active. phases: type: array items: $ref: "#/components/schemas/agentsV1Phase" description: Ordered list of phases in this plan. description: A structured plan with phases and steps. agentsV1GrepArtifactsResponse: type: object properties: pattern: type: string description: The pattern that was searched. match_count: type: integer format: int64 description: Total number of matches found (may exceed matches size if limited). matches: type: array items: $ref: "#/components/schemas/agentsV1GrepMatch" description: The matches (may be limited by request limit). description: Response for GrepArtifacts. agentsV1Tool: type: object properties: id: type: string description: |- Globally unique, stable tool identifier (hash of the original tool name). Use this to target a tool in requests. Remains constant even when the tool is renamed via adapters. readOnly: true name: type: string description: |- Human-facing display name. May change due to adapters. Do not use for lookup, routing, or invocation — use `id` instead. readOnly: true description: type: string description: Human-readable description of what the tool does. readOnly: true source_id: type: string description: |- The source that provides this tool. Can be used as a performance hint in requests to limit search scope. readOnly: true is_adapted: type: boolean description: Whether this tool has been adapted (has adapters applied). readOnly: true original_name: type: string description: The original tool name (before any adaptations, if different). readOnly: true original_description: type: string description: The original description (before any adaptations). readOnly: true status_template: type: string description: |- Optional status template for UI display during tool execution. Supports argument interpolation using ${arg} or $arg syntax. Example: "Reading ${uri}" becomes "Reading /path/to/file.txt". readOnly: true parameters: type: array items: $ref: "#/components/schemas/agentsV1ToolParameter" description: Typed parameters for this tool (adapted version, as seen by LLM). readOnly: true output: $ref: "#/components/schemas/agentsV1ValueTypeDescriptor" is_remote: type: boolean description: |- Whether the tool requires remote execution. When true, generation pauses on each call and waits for an external result via the SendToolResult API. Reflects the effective (post-adapter) value. readOnly: true requires_approval: type: boolean description: |- Whether the tool requires explicit user approval before each call. When true, the agent loop pauses on the tool call and waits for the user to Approve or Deny. Reflects the effective (post-adapter) value. readOnly: true initial_window_seconds: type: integer format: int64 description: |- How many seconds an unclaimed remote call has to be answered before it is closed out, zero meaning it never expires. Only meaningful when is_remote is true. Reflects the effective (post-adapter) value. readOnly: true lease_window_seconds: type: integer format: int64 description: |- How many seconds a claim holds a remote call open past each renewal, zero meaning it never expires. Only meaningful when is_remote is true. Reflects the effective (post-adapter) value. readOnly: true execution_window_seconds: type: integer format: int64 description: |- How many seconds a local call may run before it is abandoned and reported as a timeout, zero meaning it is never abandoned. Only meaningful when is_remote is false. Reflects the effective (post-adapter) value. readOnly: true description: A tool that can be called by an AI agent. agentsV1GetAgentResponse: type: object properties: id: type: string description: The agent's unique identifier. name: type: string description: The agent's display name. variables: type: array items: $ref: "#/components/schemas/agentsV1VariableDefinition" description: |- Variable definitions for thread-scoped configuration. Variables can be referenced in any config using `$varName` syntax. sub_agents: type: array items: $ref: "#/components/schemas/agentsV1SubAgent" description: Sub-agents configured for this agent. description: type: string description: Optional description of the agent's purpose. version: type: string format: uint64 description: |- The version number of the returned agent. When loaded by tag or version, this is the resolved version. When loaded as latest, this is the latest version. tags: type: array items: type: string description: Tags applied to the returned version. auto_title_enabled: type: boolean description: |- Whether the agent automatically generates a title and description for each new thread on the first user message. customization_explainer_enabled: type: boolean description: |- Whether the agent generates a plain-English summary every time a thread's customization changes. The summaries are surfaced in the customization badge tooltip. abilities: type: array items: $ref: "#/components/schemas/agentsV1Ability" description: The agent's abilities, as shown on the agent card. icon: type: string description: |- The agent's effective icon, as a kebab-case Lucide icon name. Empty when the agent has no icon. description: Response message for GetAgent. agentsV1ToolApprovalReply: type: object properties: tool_call_id: type: string description: The tool_call_id from the ToolApprovalRequested event. approved: type: boolean description: True for approval, false for denial. reason: type: string description: Optional reason. Populated on denial; ignored on approval. description: |- User's reply to a pending tool-approval request. Posted via SendMessageSync when the user clicks Approve or Deny on the approval card. The handler appends ToolApprovalGranted or ToolApprovalDenied to the thread event log and re-enters the agent loop. agentsThreadServiceGrepArtifactsBody: type: object properties: pattern: type: string description: Required. Regex pattern to search for. prefix: type: string description: Optional. URI prefix to limit search scope (e.g., "workspace://src/"). glob: type: string description: Optional. Glob pattern to filter files (e.g., "*.rs"). ignore_case: type: boolean description: Optional. Case-insensitive search. context_lines: type: integer format: int64 description: Optional. Number of context lines before/after each match. limit: type: integer format: int64 description: Optional. Maximum number of matches to return. description: Request for GrepArtifacts. required: - pattern agentsThreadServiceCommitArtifactsBody: type: object properties: prefix: type: string description: |- Optional. Store prefix to limit commit scope (e.g., "workspace://"). If not specified, commits all staged changes across all stores. description: Request for CommitArtifacts. agentsThreadServiceStartCompactionBody: type: object properties: from_event_id: type: string format: uint64 description: |- Optional. The event ID from which to start compaction. Events from this ID onwards (inclusive) will be compacted. If not specified, the entire conversation is compacted. description: |- Request to start context compaction for a thread. Compaction summarizes conversation history to reduce context size while preserving essential information. A CompactStart event is emitted immediately, and an external compaction process should later emit CompactComplete with the summary. agentsV1StepStatus: type: string enum: - STEP_STATUS_UNSPECIFIED - STEP_STATUS_PENDING - STEP_STATUS_COMPLETED - STEP_STATUS_FAILED - STEP_STATUS_SKIPPED default: STEP_STATUS_UNSPECIFIED description: |- Status of a plan step. - STEP_STATUS_UNSPECIFIED: Unspecified step status. - STEP_STATUS_PENDING: Step has not started yet. - STEP_STATUS_COMPLETED: Step completed successfully. - STEP_STATUS_FAILED: Step failed. - STEP_STATUS_SKIPPED: Step was skipped. agentsV1GetArtifactsStagingSummaryResponse: type: object properties: staging_enabled: type: boolean description: Whether staging is enabled for any stores. changes: type: array items: $ref: "#/components/schemas/agentsV1StagedChange" description: List of staged changes (metadata only, no diff content). total_changes: type: integer format: int64 description: Total number of staged changes. additions: type: integer format: int64 description: Number of additions. modifications: type: integer format: int64 description: Number of modifications. deletions: type: integer format: int64 description: Number of deletions. description: Response for GetArtifactsStagingSummary. agentsAgentServiceExportAgentBody: type: object properties: format: type: string description: Required. The export format kind (e.g., "yaml", "kubernetes"). config: type: object description: Format-specific configuration options. description: Request message for ExportAgent. required: - format agentsThreadServiceSetFeedbackBody: type: object properties: generation_id: type: string description: Required. The generation ID (from GenerationComplete.id). feedback_type: $ref: "#/components/schemas/agentsV1FeedbackType" description: Request to set feedback for a generation response. agentsV1ListArtifactsResponse: type: object properties: artifacts: type: array items: $ref: "#/components/schemas/agentsV1Artifact" description: Artifacts matching the filter. common_prefixes: type: array items: type: string description: Common prefixes ("folders") when delimiter is set. description: Response for ListArtifacts. agentsV1Artifact: type: object properties: id: type: string description: "Unique identifier (URI format: {store_id}://{path})." readOnly: true name: type: string description: Path-based name (e.g., "src/main.rs", "docs/design.md"). readOnly: true mime_type: type: string description: MIME type (e.g., "text/plain", "application/json", "image/png"). readOnly: true size: type: string format: uint64 description: Size in bytes. readOnly: true created_at: type: string format: date-time description: Creation timestamp. readOnly: true updated_at: type: string format: date-time description: Last modification timestamp. readOnly: true description: type: string description: Optional description. version: type: string format: uint64 description: Optimistic concurrency version (epoch nanoseconds). readOnly: true description: An artifact stored in an artifact store. agentsThreadServiceDeactivatePlanBody: type: object properties: {} description: Request to deactivate a thread's plan. agentsV1ListSubAgentsResponse: type: object properties: sub_agents: type: array items: $ref: "#/components/schemas/agentsV1SubAgent" description: The sub-agents configured for the thread. is_customized: type: boolean description: Whether this represents a per-thread customization (vs inherited from agent). description: Response message for ListSubAgents. agentsThreadServiceUpdateThreadBody: type: object properties: title: type: string description: Optional new title for the thread. description: type: string description: Optional new description for the thread. description: Request to update a thread's metadata. agentsThreadServiceSendToolCallBody: type: object properties: tool_name: type: string description: Required. Tool name as advertised by the agent's tool catalog. arguments: type: object additionalProperties: $ref: "#/components/schemas/agentsV1Value" description: |- Arguments to the tool, keyed by parameter name. Each Value carries the typed argument exactly as a generator would have produced it. description: |- Request to inject a deterministic tool call into a thread. Appends an assistant-voice preamble announcing the call as an externally requested action, then a synthetic ToolCallStart (and one ToolCallArgument per supplied argument) to the thread event log under the generation lock, executes the tool through the normal dispatcher, and continues with an LLM turn that has the tool result in context. The preamble keeps the model from misattributing the call to itself. agentsThreadServiceResetPlanBody: type: object properties: {} description: Request to reset all steps in a thread's plan back to pending. agentsV1ToolSource: type: object properties: source_id: type: string description: |- The unique source identifier. Generated unless the creator supplied one, as client-declared capabilities do (`client:`). readOnly: true type: type: string description: The source type (e.g., "rust", "grpc", "memory"). readOnly: true display_name: type: string description: Human-readable label for the source type. readOnly: true description: type: string description: Description of this tool source. readOnly: true config: type: object description: The current configuration of this source. readOnly: true tool_adapters: type: object additionalProperties: $ref: "#/components/schemas/agentsV1ToolAdapterChain" description: |- Per-tool adapter chains. Key is tool ID (stable hash of original tool name), value is the ordered chain of adapters. Adapters are applied in order: first adapter wraps the tool, second adapter wraps the first, etc. description: A configured tool source belonging to an agent. agentsThreadServiceCreateThreadBody: type: object properties: title: type: string description: Optional human-readable title for the thread. description: type: string description: Optional description of the thread's purpose or context. variables: type: object additionalProperties: type: string description: |- Variables for thread-scoped configuration resolution. These values fill the variables defined in the agent's configuration. description: Request to create a new thread. agentsV1GetArtifactDiffResponse: type: object properties: has_changes: type: boolean description: Whether this artifact has staged changes. change: $ref: "#/components/schemas/agentsV1StagedChange" diff: type: string description: |- Unified diff content. Empty for binary files, deleted artifacts, or if no changes. description: Response for GetArtifactDiff. agentsV1ExportAgentResponse: type: object properties: data: type: string format: byte description: The exported agent data. filename: type: string description: Suggested filename for the export (e.g., "my-agent.yaml"). content_type: type: string description: MIME type of the exported data (e.g., "application/x-yaml"). description: Response message for ExportAgent. agentsV1ListAgentsResponse: type: object properties: agents: type: array items: $ref: "#/components/schemas/agentsV1AgentDescriptor" description: The agents on this page, with their metadata. total_size: type: integer format: int32 description: |- Total agents matching the parent scope AND query AND filter, across all pages. order_by: type: string description: |- The order applied to this page, normalised (e.g. "updated_at desc"). The surface default when the request left `order_by` empty. description: Response message for ListAgents. agentsV1RestoreAgentVersionResponse: type: object properties: version: $ref: "#/components/schemas/agentsV1AgentVersionInfo" description: Response after restoring a previous agent version. agentsV1Event: type: object properties: id: type: string format: uint64 description: |- Sequence ID within the thread (0-indexed). Used for SSE Last-Event-ID reconnection support. Only present when events are retrieved from a thread context. task_id: type: string description: |- Scopes this event to a sub-agent task. Not set for parent (top-level) scope events. recorded_at_ms: type: string format: int64 description: |- Wall-clock time the event was recorded (appended to the store), in milliseconds since the Unix epoch. Present for persisted events; absent for ephemeral (id-less) notifications. Consumers derive a thread's status-change time from this recorded time. deleted: type: boolean description: |- Whether this event belongs to a deleted turn. Only set when include_deleted is true in the request. instruction_text: $ref: "#/components/schemas/agentsV1InstructionText" input_text: $ref: "#/components/schemas/agentsV1InputText" input_image: $ref: "#/components/schemas/agentsV1InputImage" output_text: $ref: "#/components/schemas/agentsV1OutputText" tool_call_start: $ref: "#/components/schemas/agentsV1ToolCallStart" tool_call_argument: $ref: "#/components/schemas/agentsV1ToolCallArgument" tool_result: $ref: "#/components/schemas/agentsV1ToolResult" generation_complete: $ref: "#/components/schemas/agentsV1GenerationComplete" reasoning_text: $ref: "#/components/schemas/agentsV1ReasoningText" reasoning_summary: $ref: "#/components/schemas/agentsV1ReasoningSummary" generation_failed: $ref: "#/components/schemas/agentsV1GenerationFailed" interrupt: $ref: "#/components/schemas/agentsV1Interrupt" interrupt_answer: $ref: "#/components/schemas/agentsV1InterruptAnswer" compact_start: $ref: "#/components/schemas/agentsV1CompactStart" compact_complete: $ref: "#/components/schemas/agentsV1CompactComplete" compact_failed: $ref: "#/components/schemas/agentsV1CompactFailed" reminder: $ref: "#/components/schemas/agentsV1Reminder" input_document: $ref: "#/components/schemas/agentsV1InputDocument" task_requested: $ref: "#/components/schemas/agentsV1TaskRequested" task_completed: $ref: "#/components/schemas/agentsV1TaskCompleted" task_failed: $ref: "#/components/schemas/agentsV1TaskFailed" follow_up: $ref: "#/components/schemas/agentsV1FollowUp" tool_approval_requested: $ref: "#/components/schemas/agentsV1ToolApprovalRequested" tool_approval_granted: $ref: "#/components/schemas/agentsV1ToolApprovalGranted" tool_approval_denied: $ref: "#/components/schemas/agentsV1ToolApprovalDenied" sleep_requested: $ref: "#/components/schemas/agentsV1SleepRequested" sleep_completed: $ref: "#/components/schemas/agentsV1SleepCompleted" transfer_requested: $ref: "#/components/schemas/agentsV1TransferRequested" transfer_completed: $ref: "#/components/schemas/agentsV1TransferCompleted" transfer_failed: $ref: "#/components/schemas/agentsV1TransferFailed" task_started: $ref: "#/components/schemas/agentsV1TaskStarted" task_suspended: $ref: "#/components/schemas/agentsV1TaskSuspended" task_resumed: $ref: "#/components/schemas/agentsV1TaskResumed" sleep_failed: $ref: "#/components/schemas/agentsV1SleepFailed" events_deleted: $ref: "#/components/schemas/agentsV1EventsDeleted" event_enqueued: $ref: "#/components/schemas/agentsV1EventEnqueued" event_popped: $ref: "#/components/schemas/agentsV1EventPopped" input_artifact: $ref: "#/components/schemas/agentsV1InputArtifact" description: |- An event in a generation sequence. Events represent all occurrences during generation, both from input (instructions, prompts, tool results) and output (generated text, tool calls, generation metadata). agentsV1AgentVersionInfo: type: object properties: version: type: string format: uint64 description: Auto-incrementing version number (1-based). tags: type: array items: type: string description: User-applied tags on this version. created_at: type: string format: date-time description: When this version was created. created_by: $ref: "#/components/schemas/agentsV1PrincipalRef" description: Metadata for a single stored version of an agent. agentsThreadServiceSendMessageSyncBody: type: object properties: message: $ref: "#/components/schemas/agentsV1UserMessage" interrupt_reply: $ref: "#/components/schemas/agentsV1InterruptReply" tool_approval_reply: $ref: "#/components/schemas/agentsV1ToolApprovalReply" description: Request to send a message and stream response events synchronously. agentsV1ThreadOrigin: type: object properties: kind: type: string description: |- Stable discriminator equal to the set `detail` arm's name ("schedule", "sub_agent", ...). Lets generic clients and filters switch on the kind without knowing every variant. schedule: $ref: "#/components/schemas/agentsV1ScheduleOrigin" sub_agent: $ref: "#/components/schemas/agentsV1SubAgentOrigin" description: |- Why a thread was created. Absent on a thread means it was started directly (the normal interactive flow). New kinds are added as additional `detail` arms without breaking existing ones. agentsV1ToolParameter: type: object properties: name: type: string description: The parameter name. readOnly: true description: type: string description: Human-readable description of the parameter. readOnly: true value_type: $ref: "#/components/schemas/agentsV1ValueTypeDescriptor" required: type: boolean description: Whether this parameter is required. readOnly: true description: A tool parameter with semantic type information. agentsV1CompactFailed: type: object properties: compact_id: type: string description: Unique identifier linking to CompactStart. message: type: string description: Human-readable error message. description: Marks the failure of a compaction operation. agentsV1UserMessage: type: object properties: content: type: string description: The message text content. images: type: array items: $ref: "#/components/schemas/agentsV1UserImage" description: Optional images to include with the message. documents: type: array items: $ref: "#/components/schemas/agentsV1UserDocument" description: Optional documents to include with the message. description: A user message with optional attachments. agentsV1InstructionText: type: object properties: text: type: string description: The instruction text. mutable: type: boolean description: |- Whether the text is expected to change between turns (e.g. a writable memory block). Generators that support prompt caching use this to keep volatile content outside the cached prefix. id: type: string description: |- Stable identifier when the instruction comes from a named source (e.g. a memory block id). Unset for freeform instructions. description: |- Instruction text providing context or directives. Typically appears at the beginning to set generator behavior. agentsV1UserImage: type: object properties: uri: type: string description: URI or data URI of the image. detail: type: string description: Level of detail for image processing (optional). description: An image attached to a user message. agentsV1TaskRequested: type: object properties: call_id: type: string title: |- The invoke_agent_* tool-call id. The recording-stable handle the LLM uses to address the task on resume. (No task_id yet — the sub-thread does not exist until TaskStarted.) sub_agent_id: type: string description: The configured sub-agent ID to invoke. input: type: string description: The message/input to send to the sub-agent. artifacts: type: array items: type: string description: Artifact URIs to hand to the sub-agent, materialized into its uploads. variables: type: object additionalProperties: type: string description: Per-invocation values for the target agent's exposed variables. opaque: type: string format: byte description: Provider-specific opaque blob for faithful replay (e.g. Gemini thought_signature). description: Sub-agent invocation requested by the LLM. agentsV1ToolApprovalGranted: type: object properties: tool_call_id: type: string description: The tool_call_id from the corresponding ToolApprovalRequested event. description: |- User granted approval for a pending tool call. Resume scan dispatches the tool when this event is present without a matching ToolResult. agentsV1Value: type: object properties: string_value: type: string description: A string value. number_value: type: number format: double description: A floating-point number. integer_value: type: string format: int64 description: An integer. bool_value: type: boolean description: A boolean. binary_value: type: string format: byte description: Raw binary data. artifact_value: $ref: "#/components/schemas/agentsV1ArtifactValue" artifact_uri_value: $ref: "#/components/schemas/agentsV1ArtifactUriValue" date_value: $ref: "#/components/schemas/agentsV1DateValue" time_value: $ref: "#/components/schemas/agentsV1TimeValue" date_time_value: $ref: "#/components/schemas/agentsV1DateTimeValue" duration_value: $ref: "#/components/schemas/agentsV1DurationValue" list_value: $ref: "#/components/schemas/agentsV1ListValue" object_value: $ref: "#/components/schemas/agentsV1ObjectValue" null_value: $ref: "#/components/schemas/agentsV1NullValue" description: |- A typed runtime value. Mirrors rain_value::Value — carries both the data and enough metadata (mime_type, filename) for consumers to handle it correctly. agentsV1FollowUp: type: object properties: suggestion: type: string description: The suggested follow-up message text. description: |- A streamed follow-up suggestion chip. Ephemeral: not persisted, only streamed to SSE clients. agentsV1ResetEventsResponse: type: object description: Response for ResetEvents. agentsV1GetEventsResponse: type: object properties: events: type: array items: $ref: "#/components/schemas/agentsV1Event" description: The events in the thread, ordered chronologically. description: Response message for GetEvents. agentsV1DiffArtifactsResponse: type: object properties: entries: type: array items: $ref: "#/components/schemas/agentsV1DiffEntry" description: List of staged changes with optional diff content. total_changes: type: integer format: int64 description: Total number of staged changes. additions: type: integer format: int64 description: Number of additions. modifications: type: integer format: int64 description: Number of modifications. deletions: type: integer format: int64 description: Number of deletions. description: Response for DiffArtifacts. agentsV1ListThreadsResponse: type: object properties: threads: type: array items: $ref: "#/components/schemas/agentsV1Thread" description: The threads for the agent. description: Response message for ListThreads. agentsV1AgentDescriptor: type: object properties: id: type: string description: The agent's unique identifier. name: type: string description: The agent's display name. description: type: string description: Optional description of the agent's purpose. read_only: type: boolean description: Whether this agent is read-only (e.g. the default agent). latest_version: type: string format: uint64 description: Latest version number, if the store supports versioning. latest_tags: type: array items: type: string description: Tags applied to the latest version. last_updated_at: type: string format: date-time description: When the latest version was created (last update time). created_by: $ref: "#/components/schemas/agentsV1PrincipalRef" updated_by: $ref: "#/components/schemas/agentsV1PrincipalRef" created_at: type: string format: date-time description: When the agent was created (first save). rating: type: number format: double description: |- Aggregated user-feedback rating in [0, 1] (Wilson lower bound), projected to the latest version. Absent when no feedback has been recorded. abilities: type: array items: $ref: "#/components/schemas/agentsV1Ability" description: |- The agent's abilities, as shown on the agent card. Empty when the agent has no abilities. icon: type: string description: |- The agent's icon, as a kebab-case Lucide icon name. Empty when the agent has no icon. stats: type: object additionalProperties: type: string description: |- Derived, presentational metadata about the agent, e.g. {"model": "gpt-4o", "generator_kind": "openai", "tool_count": "12", "context_window": "128000"}. Keys are open-ended; clients read the ones they recognize and ignore the rest. Values are strings; numeric values are stringified. A key is absent when it has no value for the agent (e.g. an agent with no fixed model omits "model"). has_plan: type: boolean description: |- Whether the agent defines a base plan. A promptless schedule requires one (each run executes the plan), so clients gate that affordance on it. labels: type: array items: type: string description: |- Freeform labels describing the agent as a whole, e.g. "finance", "internal-tool". Unlike `latest_tags`, which names one immutable version, these belong to the agent and do not change as versions come and go. description: Descriptor for an agent with basic metadata. agentsAgentServiceTagAgentVersionBody: type: object properties: tag: type: string description: The tag name to apply. description: Request to apply a tag to a specific agent version. agentsV1Interrupt: type: object properties: interrupt_id: type: string description: Unique identifier for this interrupt (for correlating reply). questions: type: array items: $ref: "#/components/schemas/agentsV1InterruptQuestion" description: The questions to ask the user. opaque: type: string format: byte description: |- Provider-specific opaque data required for multi-turn replay. Gemini: the thoughtSignature from the ask_user function call. description: |- Generation paused - LLM is asking the user question(s). This is a terminal event (like GenerationComplete) - no more events follow until the user responds. agentsThreadServiceForkThreadBody: type: object properties: title: type: string description: Optional title for the new thread. Defaults to "Fork of {source_title}". description: Request message for ForkThread (duplicate a thread with all its data). agentsV1CommitArtifactsResponse: type: object properties: committed_count: type: integer format: int64 description: Number of artifacts committed. additions: type: integer format: int64 description: Number of additions committed. modifications: type: integer format: int64 description: Number of modifications committed. deletions: type: integer format: int64 description: Number of deletions committed. version: type: string description: |- New artifact version produced by this commit, if the store versions its contents. Absent for stores without a version concept. description: Response for CommitArtifacts. agentsV1ArtifactUriValue: type: object properties: uri: type: string mime_type: type: string filename: type: string description: An artifact URI reference with optional metadata. agentsV1ToolApprovalRequested: type: object properties: tool_call_id: type: string description: The tool_call_id from the corresponding ToolCallStart event. description: |- Approval requested for a pending tool call. Emitted when a tool's requires_approval flag is true after the model emits the corresponding ToolCallStart. The agent loop pauses (turn returns interrupted) until a matching ToolApprovalGranted or ToolApprovalDenied event is appended to the thread. agentsV1WakeResponse: type: object properties: woken: type: boolean description: |- True if a pending sleep was found and ended early. False when the thread was not currently sleeping (the call still triggers a normal resume in that case, but no SleepCompleted is appended). description: Response for waking a sleeping thread. agentsV1DurationValue: type: object properties: seconds: type: string format: int64 nanos: type: integer format: int32 description: A duration in seconds and nanoseconds. agentsV1UpdateAgentResponse: type: object properties: id: type: string description: The agent's unique identifier. name: type: string description: The updated display name. description: type: string description: The updated description. version: type: string format: uint64 description: |- The new version number, if a new version was created. None if the template was identical to the current latest version. labels: type: array items: type: string description: |- The agent's labels after the update, normalised: trimmed, de-duplicated, and re-cased to match any spelling already in use elsewhere. Always populated, whether or not the request carried labels, so a client can see what its input resolved to. description: Response message for UpdateAgent. agentsV1SleepCompleted: type: object properties: sleep_id: type: string description: Equal to the sleep_id of the matching SleepRequested. slept_for_seconds: type: string format: uint64 description: How long we actually slept, in seconds. woke_at: type: string format: int64 description: Wall-clock time we woke (Unix seconds). interrupted_by_user: type: boolean description: |- True when the sleep was cut short by a user message arriving while the thread was sleeping; false when the scheduled wake fired naturally. description: Sleep ended and the thread is being resumed. agentsAgentServiceUpdateAgentBody: type: object properties: name: type: string description: The new display name for the agent. labels: $ref: "#/components/schemas/agentsV1AgentLabels" description: |- Request to edit an agent's own identity. Renaming and relabelling are the only direct edits to a base agent — its description, abilities, and feature toggles are deployable configuration, edited on a thread and promoted by Deploy, never written here. agentsV1ToolCallStart: type: object properties: index: type: integer format: int32 description: Index of this tool call (for parallel tool calls). id: type: string description: Unique identifier for this tool call. name: type: string description: Name of the tool being called. is_remote: type: boolean description: |- Whether this tool requires remote execution. Remote tools pause generation and wait for an external system to execute them and post the result back via API. status_template: type: string description: |- Optional status template for UI display during tool execution. Supports argument interpolation using ${arg} or $arg syntax. Example: "Reading ${uri}" becomes "Reading /path/to/file.txt". opaque: type: string format: byte description: |- Provider-specific opaque data required for multi-turn replay. Gemini: the thoughtSignature from function call parts. description: Tool call initiated by the generator. agentsV1ArtifactValue: type: object properties: data: type: string format: byte mime_type: type: string filename: type: string description: "An artifact value: binary data with optional metadata." agentsV1SleepRequested: type: object properties: sleep_id: type: string description: |- Correlation handle. Equal to the ScheduledTaskId registered with the scheduler, and equal to sleep_id echoed in the matching SleepCompleted. requested_at: type: string format: int64 description: Wall-clock time the request was emitted (Unix seconds). wake_at: type: string format: int64 description: Wall-clock time the wake is scheduled for (Unix seconds). seconds: type: integer format: int64 description: Requested duration in seconds (post-clamp to the operator cap). reason: type: string description: Optional reason, copied through from the tool call arguments. opaque: type: string format: byte description: Provider-specific opaque data required for multi-turn replay. description: |- Generation paused — LLM called the synthetic `sleep` tool. Terminal event, like Interrupt. The agent runner schedules the wake and exits; resumption happens via SleepCompleted appended by the AgentWakeHandler (or by the message-receive path on user interrupt). agentsThreadServiceUpdateArtifactBody: type: object properties: mime_type: type: string description: Required. The MIME type. data: type: string format: byte description: Required. The artifact content. description: type: string description: Optional description. description: Request for UpdateArtifact. required: - mime_type - data agentsThreadServiceDeleteEventBody: type: object properties: event_id: type: string format: uint64 description: |- Deletes an event and its entire associated turn from the thread. The event_id must refer to an InputText event that starts a turn. This deletes all events in the turn: the initiating InputText, all generation output (text, tool calls, tool results, reasoning, interrupts and their answers), and terminal events (GenerationComplete/GenerationFailed) through all generation cycles until the next InputText event. Returns INVALID_ARGUMENT if event_id does not refer to an InputText event. agentsV1TaskResumed: type: object properties: task_id: type: string description: The delegate's sub-thread id being resumed. call_id: type: string description: The resume_agent tool-call id. answers: type: array items: $ref: "#/components/schemas/agentsV1QuestionAnswer" description: The answers to the delegate's questions. opaque: type: string format: byte description: Provider-specific opaque blob (e.g. Gemini thought_signature). description: The parent answered a suspended delegate (the resume_agent tool call). agentsV1FeedbackType: type: string enum: - FEEDBACK_TYPE_UNSPECIFIED - FEEDBACK_TYPE_LIKE - FEEDBACK_TYPE_DISLIKE default: FEEDBACK_TYPE_UNSPECIFIED description: |- Feedback type for a generation response. - FEEDBACK_TYPE_UNSPECIFIED: No feedback has been provided. - FEEDBACK_TYPE_LIKE: User liked the response. - FEEDBACK_TYPE_DISLIKE: User disliked the response. agentsV1ThreadStatus: type: object properties: state: $ref: "#/components/schemas/agentsV1ThreadStatusState" tool_label: type: string description: "ExecutingTool: the tool's rendered in-flight label." remote_count: type: integer format: int64 description: "AwaitingTool: the number of open remote calls (>= 1)." wake_at: type: string format: date-time description: "Sleeping: the scheduled wake instant." sleep_reason: type: string description: "Sleeping: optional reason copied from the sleep request." retry_attempt: type: integer format: int64 description: "Retrying: 1-indexed attempt number." retry_max_attempts: type: integer format: int64 description: "Retrying: total attempts permitted." next_attempt_at: type: string format: date-time description: "Retrying: when the next attempt is scheduled, if known." error_kind: $ref: "#/components/schemas/agentsV1GenerationErrorKind" error_message: type: string description: "Failed: human-readable error message." description: |- What a thread is doing right now. A point-in-time field that changes many times within a single turn; a pure function of the thread's event history. agentsV1InterruptQuestion: type: object properties: id: type: string description: Unique identifier for this question. question: type: string description: The full question text. header: type: string description: Short label displayed as chip/tag (max 12 chars). options: type: array items: $ref: "#/components/schemas/agentsV1InterruptOption" description: Available choices (2-4 options). multi_select: type: boolean description: If true, user can select multiple options. description: A single question in an interrupt. agentsV1Phase: type: object properties: name: type: string description: Name of the phase. description: type: string description: Description of the phase. steps: type: array items: $ref: "#/components/schemas/agentsV1Step" description: Ordered list of steps in this phase. description: A phase containing ordered steps. agentsV1DehydrationState: type: object properties: dehydrated_at: type: string format: date-time description: When the thread was dehydrated. dehydrated_by: $ref: "#/components/schemas/agentsV1PrincipalRef" size_bytes: type: string format: uint64 description: Size of the archive in bytes. description: |- Operational dehydration lifecycle state for a thread. Present iff the thread has been dehydrated (its data archived, leaving a tombstone). The archive's storage internals are server-side only; clients see just when and by whom the thread was dehydrated and how large the archive is. agentsThreadServiceDiscardArtifactsBody: type: object properties: {} description: Request for DiscardArtifacts. agentsV1GetThreadContextResponse: type: object properties: items: type: array items: $ref: "#/components/schemas/agentsV1ContextItem" description: List of context items contributing to the thread's context window. readOnly: true model_info: $ref: "#/components/schemas/agentsV1ModelInfo" summary: $ref: "#/components/schemas/agentsV1ContextSummary" auto_compact_tokens: type: integer format: int64 description: |- Prompt token count at which the next completed turn triggers auto-compaction. Absent when no compactor is configured, in which case auto-compaction never fires, or when the model does not report a context window. readOnly: true description: Response containing thread context information. agentsV1ToolApprovalDenied: type: object properties: tool_call_id: type: string description: The tool_call_id from the corresponding ToolApprovalRequested event. reason: type: string description: Optional reason supplied by the user when denying. description: |- User denied approval for a pending tool call. Resume scan synthesizes a ToolResult with success=false and the reason in the error field when this event is present without a matching ToolResult. agentsV1QuestionAnswer: type: object properties: question_id: type: string description: The question ID being answered. selected: type: array items: type: string description: Selected option label(s). Multiple for multi_select questions. description: A single question's answer. agentsV1ListAgentVersionsResponse: type: object properties: versions: type: array items: $ref: "#/components/schemas/agentsV1AgentVersionInfo" description: All versions in ascending order. description: Response containing the version history of an agent. agentsThreadServiceActivatePlanBody: type: object properties: {} description: Request to activate a thread's plan. agentsV1ToolAdapterChain: type: object properties: adapters: type: array items: $ref: "#/components/schemas/agentsV1ToolAdapterDescriptor" description: List of adapters applied to this tool. description: |- A chain of adapters for a single tool. Adapters are applied in order: first adapter wraps the tool, second adapter wraps the first, etc. agentsV1DateValue: type: object properties: year: type: integer format: int32 month: type: integer format: int32 day: type: integer format: int32 description: A date value with year, month, day components. agentsV1SetFeedbackResponse: type: object properties: feedback_type: $ref: "#/components/schemas/agentsV1FeedbackType" previous_feedback_type: $ref: "#/components/schemas/agentsV1FeedbackType" description: Response for setting feedback on a generation. agentsV1EventPopped: type: object properties: priority: $ref: "#/components/schemas/agentsV1QueuePriority" events: type: array items: $ref: "#/components/schemas/agentsV1Event" description: The events forming the drained group, verbatim. description: |- The durable queue head was drained (enacted). Broadcast-only. Carries the drained group so subscribers can match-and-remove it. agentsV1GenerationFailed: type: object properties: message: type: string description: Human-readable error message. kind: $ref: "#/components/schemas/agentsV1GenerationErrorKind" retryable: type: boolean description: |- When `true`, the agent loop is automatically retrying this generation; the next attempt fires at `next_attempt_at`. When `false`, this is a terminal failure (either non-retryable by classification, or the retry budget is exhausted). attempt: type: integer format: int64 description: |- 1-indexed attempt number that this failure corresponds to. Zero when `retryable` is false and the field is unused. max_attempts: type: integer format: int64 description: |- Total attempts permitted in this retry budget. Zero when `retryable` is false and the field is unused. next_attempt_at: type: string format: date-time description: |- Wall-clock instant at which the next attempt is scheduled. Absent when `retryable` is false. usage: $ref: "#/components/schemas/agentsV1Usage" model: type: string description: Model the failed attempt ran on, when known. provider: type: string description: Generator kind of the failed attempt, when known. description: |- Generation failed with an error. The error message should be displayed to the user. agentsToolCatalogServiceEnableToolsBody: type: object properties: tool_ids: type: array items: type: string description: |- Required. The tool IDs to enable (added to existing enabled set). Tool IDs are stable hashes of the original tool name. description: Request message for EnableTools (batch enable, additive). required: - tool_ids agentsV1RestoreEventResponse: type: object properties: from_event_id: type: string format: uint64 to_event_id: type: string format: uint64 agentsV1Step: type: object properties: name: type: string description: Name of the step. description: type: string description: Description of what needs to be done. acceptance_criteria: type: string description: Criteria for determining when the step is complete. status: $ref: "#/components/schemas/agentsV1StepStatus" failure_reason: type: string description: Reason for failure (only set when status is FAILED). description: A single step within a phase. agentsV1ListToolsResponse: type: object properties: tools: type: array items: $ref: "#/components/schemas/agentsV1Tool" description: The tools available to the agent. is_customized: type: boolean description: |- Whether this represents a per-thread tool-level override. True when the flat (source, tool, name, adapters, metadata) view differs from the pinned agent version's tools. Independent of `ListToolSources.is_customized`, which only flags source-identity changes. description: Response message for ListTools. agentsThreadServiceDiffArtifactsBody: type: object properties: prefix: type: string description: |- Optional. Store prefix to limit diff scope (e.g., "workspace://"). If not specified, returns diff for all stores. include_content: type: boolean description: |- Optional. Include unified diff content for each change. Default is false (summary only). description: Request for DiffArtifacts. agentsThreadServiceSendToolResultBody: type: object properties: tool_call_id: type: string description: Required. The ID of the tool call (from ToolCallStart.id). content: $ref: "#/components/schemas/agentsV1Value" success: type: boolean description: Whether the tool execution was successful. error: type: string description: |- Error message if the tool execution failed (optional). When set, success should be false. duration_micros: type: string format: uint64 description: Duration of tool execution in microseconds (optional). description: |- Request to send a tool execution result for a remote tool. Remote tools pause generation when called, waiting for an external system to execute them and return the result via this RPC. Generation resumes once the result is received. agentsV1InputImage: type: object properties: uri: type: string description: URI or data URI of the image. detail: type: string description: Level of detail for image processing (optional). description: Input image for vision models. agentsV1VariableDefinition: type: object properties: name: type: string description: The variable name (used as `$name` in configs). required: type: boolean description: Whether this variable is required when creating a thread. default: type: string description: Default value if not provided (only valid for non-required variables). description: type: string description: Human-readable description of what this variable is for. segment: type: string description: |- URL path segment name for multi-tenant parent path routing. When set, this variable can be extracted from a parent path like `/organizations/acme/workspaces/dev` where `organizations` and `workspaces` are segment names. If not set, the variable `name` is used as the segment. fixed_value: type: string description: |- Fixed value for this variable. When set, the variable is locked to this value and cannot be overridden. Unlike `default` (which can be overridden), a fixed value is immutable. description: |- Defines a variable that can be used in agent configuration. Variables are defined at the agent level and filled when creating a thread. They can be referenced in any configuration value using `$varName` syntax. agentsV1ScheduleOrigin: type: object properties: schedule_id: type: string title: |- The schedule whose occurrence created this thread. (The owning agent is implied by the thread.) occurrence_at: type: string format: date-time description: The scheduled fire time this thread corresponds to. description: A thread created because a schedule occurrence fired. agentsV1TimeValue: type: object properties: hour: type: integer format: int32 minute: type: integer format: int32 second: type: integer format: int32 description: A time value with hour, minute, second components. agentsV1TaskSuspended: type: object properties: task_id: type: string description: The delegate's sub-thread id. call_id: type: string description: The tool call this suspension resolves. interrupt_id: type: string description: The sub-thread ask_user interrupt awaiting an answer. questions: type: array items: $ref: "#/components/schemas/agentsV1InterruptQuestion" description: The questions the delegate is asking. description: The delegate paused on an ask_user interrupt. agentsV1PrincipalRef: type: object properties: id: type: string description: |- Stable identifier. For OIDC this is the `sub` claim. For trusted-header mode this is the header configured as `user_id`. For `Fixed` mode it is the configured principal's id. kind: $ref: "#/components/schemas/agentsV1PrincipalKind" email: type: string description: |- Email address if known. Optional because some IdPs don't expose one (service accounts, machine identities). display_name: type: string description: |- Human-readable display name (`name` claim, `X-Forwarded-Preferred-Username`, configured display name in Fixed mode). component: type: string description: |- For `PRINCIPAL_KIND_SYSTEM`, the in-process component that owns this attribution (`"backfill"`, `"bootstrap"`, etc.). description: |- Persistence-shape subset of a Principal stamped on stored entities as `created_by` / `updated_by`. The full Principal (with raw claims and groups) only lives in memory for the duration of a request; `PrincipalRef` is what gets persisted on agents, threads, and scheduled-task payloads. agentsV1UserDocument: type: object properties: uri: type: string description: Data URI of the document. filename: type: string description: Original filename. description: A document attached to a user message. agentsV1DiffEntry: type: object properties: change: $ref: "#/components/schemas/agentsV1StagedChange" diff: type: string description: |- Unified diff content (only if include_content was true). Empty for binary files or deleted artifacts. description: A diff entry with optional content. agentsV1Cost: type: object properties: input_nano_usd: type: string format: uint64 description: Fresh-input tokens priced at the input rate. cache_read_nano_usd: type: string format: uint64 description: Cache reads priced at the cache-read rate. cache_write_nano_usd: type: string format: uint64 description: Cache writes priced at their per-TTL rates. output_nano_usd: type: string format: uint64 description: Output tokens priced at the output rate. total_nano_usd: type: string format: uint64 description: Sum of the four classes. estimated: type: boolean description: |- Some component was priced through a loud fallback (missing cache rate, unknown cache-write TTL, legacy usage semantics, or an ambiguous rate-card lookup) — the figure is an estimate, not exact. description: |- A computed USD cost in integer nano-USD, per billing class. Never persisted — always computed on request from the effective-dated rate card, so rate corrections apply retroactively while the underlying token accounting stays immutable. agentsV1ValueTypeDescriptor: type: object properties: string_type: $ref: "#/components/schemas/agentsV1EmptyType" number_type: $ref: "#/components/schemas/agentsV1EmptyType" integer_type: $ref: "#/components/schemas/agentsV1EmptyType" boolean_type: $ref: "#/components/schemas/agentsV1EmptyType" binary_type: $ref: "#/components/schemas/agentsV1EmptyType" artifact_type: $ref: "#/components/schemas/agentsV1ArtifactValueType" artifact_uri_type: $ref: "#/components/schemas/agentsV1ArtifactValueType" literal_string_type: $ref: "#/components/schemas/agentsV1LiteralStringType" date_type: $ref: "#/components/schemas/agentsV1EmptyType" time_type: $ref: "#/components/schemas/agentsV1EmptyType" date_time_type: $ref: "#/components/schemas/agentsV1EmptyType" duration_type: $ref: "#/components/schemas/agentsV1EmptyType" list_type: $ref: "#/components/schemas/agentsV1ListType" object_type: $ref: "#/components/schemas/agentsV1ObjectType" dictionary_type: $ref: "#/components/schemas/agentsV1DictionaryType" optional_type: $ref: "#/components/schemas/agentsV1OptionalType" enum_type: $ref: "#/components/schemas/agentsV1EnumType" any_type: $ref: "#/components/schemas/agentsV1EmptyType" null_type: $ref: "#/components/schemas/agentsV1EmptyType" description: type: string description: Optional description of this value type. description: |- Semantic type descriptor for tool parameters and outputs. Represents the semantic meaning of a value type, enabling type-appropriate UI widgets beyond what raw JSON Schema can express. agentsV1TaskCompleted: type: object properties: task_id: type: string description: The delegate's sub-thread id (task identity). result: type: string description: Collected output text from the sub-agent. call_id: type: string description: The tool call this completion resolves (invoke or the last resume). description: Sub-agent invocation completed. agentsV1InputText: type: object properties: text: type: string description: The input text. description: Input text prompting the generator. agentsV1ReasoningSummary: type: object properties: text: type: string description: The reasoning summary text. description: |- Summary of the model's reasoning process. Only available with OpenAI Responses API for reasoning models. agentsV1ContextSummary: type: object properties: fixed_tokens: type: integer format: int64 description: Tokens used by fixed context (immutable memory + tools). readOnly: true volatile_tokens: type: integer format: int64 description: Tokens used by volatile context (mutable memory). readOnly: true compactable_tokens: type: integer format: int64 description: Tokens used by compactable context (conversation). readOnly: true total_used_tokens: type: integer format: int64 description: Total tokens currently in use. readOnly: true available_tokens: type: integer format: int64 description: Tokens available before hitting the context limit. readOnly: true description: Summary of token usage by category. agentsV1GenerationComplete: type: object properties: usage: $ref: "#/components/schemas/agentsV1Usage" model: type: string description: Model that was used for generation. id: type: string description: Unique response identifier. agent_version: type: string format: uint64 description: |- Agent version active when this generation ran. Absent for events written before this field existed (the rating update falls back to the thread's pinned version for those). provider: type: string description: |- Generator kind that produced this completion (e.g. "anthropic", "bedrock"), stamped by the agent loop so rate-card lookup is exact. Absent for events written before this field existed. description: |- Generation completed successfully. This is always the final event in both streaming and non-streaming modes. agentsV1GrepMatch: type: object properties: id: type: string description: Artifact ID containing the match. readOnly: true name: type: string description: Artifact name/path. readOnly: true line: type: integer format: int64 description: Line number (1-indexed). readOnly: true content: type: string description: The matching line content. readOnly: true context_before: type: array items: type: string description: Lines before the match (context). readOnly: true context_after: type: array items: type: string description: Lines after the match (context). readOnly: true description: A single grep match within an artifact. agentsV1InputDocument: type: object properties: uri: type: string description: Data URI of the document. filename: type: string description: Original filename. description: Input document (text files, PDFs, code files). agentsV1CompactStart: type: object properties: compact_id: type: string description: Unique identifier linking start and complete events. from_event_id: type: string format: uint64 description: |- Event ID of the first GenerationComplete or CompactComplete to include. Everything from this event to now gets compacted. If not set, compact entire conversation. description: |- Marks the start of a compaction operation. Blocks user input until CompactComplete is received. agentsV1AgentLabels: type: object properties: values: type: array items: type: string description: The full desired label set. Empty means the agent has no labels. description: |- A complete set of agent labels, used where a caller replaces the whole set rather than adding or removing individual entries. This exists so an update can distinguish "leave the labels alone" from "remove every label": a bare `repeated string` field has no presence, so both would arrive as an empty list. Wrapped in a message, absence and an empty `values` are separate signals. agentsV1EventEnqueued: type: object properties: priority: $ref: "#/components/schemas/agentsV1QueuePriority" events: type: array items: $ref: "#/components/schemas/agentsV1Event" description: The events forming the queued group, verbatim. description: |- A group was appended to the thread's durable queue. Broadcast-only (never persisted): the queue is separate store state, fetched in full via GetQueue. The first event is the discriminator for the kind of deferred work. agentsV1CompactComplete: type: object properties: compact_id: type: string description: Unique identifier linking to CompactStart. content: type: string description: The compacted content sent to LLM as context. usage: $ref: "#/components/schemas/agentsV1Usage" model: type: string description: Model the compaction generation ran on, when known. provider: type: string description: Generator kind of the compaction generation, when known. description: |- Completes a compaction operation with the compacted content. Events in the compacted range are replaced by this content when building the LLM context. agentsV1ThreadStatusState: type: string enum: - THREAD_STATUS_STATE_UNSPECIFIED - THREAD_STATUS_STATE_IDLE - THREAD_STATUS_STATE_THINKING - THREAD_STATUS_STATE_RESPONDING - THREAD_STATUS_STATE_EXECUTING_TOOL - THREAD_STATUS_STATE_DELEGATING - THREAD_STATUS_STATE_COMPACTING - THREAD_STATUS_STATE_TRANSFERRING - THREAD_STATUS_STATE_AWAITING_ANSWER - THREAD_STATUS_STATE_AWAITING_APPROVAL - THREAD_STATUS_STATE_AWAITING_TOOL - THREAD_STATUS_STATE_SLEEPING - THREAD_STATUS_STATE_DELEGATE_BLOCKED - THREAD_STATUS_STATE_RETRYING - THREAD_STATUS_STATE_FAILED - THREAD_STATUS_STATE_STOPPED default: THREAD_STATUS_STATE_UNSPECIFIED description: The set of thread status discriminants. agentsV1TaskStarted: type: object properties: task_id: type: string description: The delegate's sub-thread id — the stable task identity. call_id: type: string description: The invoke_agent_* call this task was born from. description: The delegate's sub-thread was created and its run began. agentsV1ToolAdapterDescriptor: type: object properties: id: type: string description: Unique identifier for this adapter (nanoid, server-generated). readOnly: true kind: type: string description: The adapter kind name (e.g., "jq"). readOnly: true display_name: type: string description: Human-readable display name (e.g., "JQ Transform"). readOnly: true config: type: object title: |- The adapter configuration as a generic struct. Structure depends on the kind: - "jq": {input?: string, output?: string} description: |- Descriptor for a tool adapter instance. Used in list responses, mutation responses, and adapter chains. agentsV1Reminder: type: object properties: text: type: string description: The reminder text. description: |- System-injected reminder for LLM context. Used for plan nudges and completion summaries. The raw text is stored without XML tags; each generator wraps it in tags during conversion. agentsV1TransferRequested: type: object properties: to: type: string description: The agent to receive control (a referenced local agent id, or "main"). initiated_by: $ref: "#/components/schemas/agentsV1TransferInitiator" transfer_id: type: string description: |- Unique transfer id; the originating tool call's id for agent-initiated transfers, loop-generated for operator-forced ones. message: type: string description: Optional handoff note to the target (the transfer tool's message argument). opaque: type: string format: byte description: Provider-specific opaque blob for faithful replay (e.g. Gemini thought_signature). variables: type: object additionalProperties: type: string description: |- LLM-supplied values for the target profile's exposed (unmapped, non-fixed) variables, captured from the transfer tool call. Empty for operator-forced transfers and transfer_back. description: |- The LLM or an operator requested handing the conversation to another agent on the same thread. The loop enacts it and appends TransferCompleted (or TransferFailed). agentsV1ToolResult: type: object properties: tool_call_id: type: string description: ID of the tool call this is responding to. name: type: string description: Name of the tool that was called. content: $ref: "#/components/schemas/agentsV1Value" success: type: boolean description: Whether the tool execution was successful. error: type: string description: Error message if the tool execution failed (optional). duration_micros: type: string format: uint64 description: Duration of tool execution in microseconds (optional). description: Result from executing a tool. agentsV1ReasoningText: type: object properties: text: type: string description: The reasoning text content. opaque: type: string format: byte description: |- Provider-specific opaque data required for multi-turn replay. Anthropic: the signature field from thinking blocks. OpenAI: the encrypted_content from reasoning items. progress_update: type: boolean description: |- True when this block is a progress update rather than reasoning: a short note the model writes for the user between tool calls. Clients show it as narration; it replays like any other thinking block. description: |- Reasoning text from the model's chain of thought. Only available with OpenAI Responses API for reasoning models. agentsV1OutputText: type: object properties: text: type: string description: The generated output text. description: Output text generated by the model. agentsV1Ability: type: object properties: name: type: string description: Short label, e.g. "web search", "PDF editing", "team memory". icon: type: string description: |- Icon identifier, as a kebab-case Lucide icon name (e.g. "file-text", "git-branch", "map-pin"). description: type: string description: Optional one-line description for a tooltip. description: A single human-readable agent capability shown on the agent card. agentsV1SubAgent: type: object properties: sub_agent_id: type: string description: The unique sub-agent identifier (nanoid). readOnly: true kind: type: string description: The sub-agent caller kind (e.g., "local", "a2a"). readOnly: true config: type: object description: Kind-specific configuration. readOnly: true name: type: string description: Display name shown to the LLM (e.g., "Researcher"). description: type: string description: Description of what this sub-agent does (shown to the LLM). variable_mappings: type: object additionalProperties: type: string description: "Explicit variable mappings: sub-agent var name -> value (supports $parentVar syntax)." description: A configured sub-agent belonging to an agent. agentsV1StagedChange: type: object properties: id: type: string description: The artifact URI (e.g., "workspace://src/main.rs"). change_type: $ref: "#/components/schemas/agentsV1ChangeType" size: type: string format: uint64 description: Size in bytes (for added/modified artifacts). description: A staged change to an artifact. agentsV1InputArtifact: type: object properties: uri: type: string description: |- Artifact-store URI (uploads://…, result://…, workspace://…). Never a data: URI, never an external http(s) URL. tokens: type: string format: uint64 description: |- Token cost of the attached content, measured by the read policy at clearance time. Absent on events recorded before clearance carried a token count. description: |- A reference to an artifact-store object attached to the conversation. The bytes live in the artifact store; this carries only the reference. MIME type and filename are read from artifact-store metadata, not duplicated here. Emitted by the generation loop as part of an artifact_read tool response when the entire artifact passed the read policy: the artifact is cleared for native attachment and generators resolve the URI to bytes at request build. Ingestion paths never emit it (uploads produce a Reminder). agentsV1TaskFailed: type: object properties: task_id: type: string description: The delegate's sub-thread id (task identity). message: type: string description: Error message. kind: $ref: "#/components/schemas/agentsV1GenerationErrorKind" call_id: type: string description: The tool call this failure resolves (invoke or the last resume). description: Sub-agent invocation failed. agentsV1InterruptAnswer: type: object properties: interrupt_id: type: string description: The interrupt_id being answered. answers: type: array items: $ref: "#/components/schemas/agentsV1QuestionAnswer" description: Answers to the questions. Empty if user redirected. description: |- User's answer to interrupt questions (stored as event). Empty answers list indicates user redirected with a different message. agentsV1TransferFailed: type: object properties: transfer_id: type: string description: The transfer_id of the matching TransferRequested. reason: type: string description: Why the transfer was rejected. description: A requested transfer was rejected (depth guard, unknown target). agentsV1DateTimeValue: type: object properties: rfc3339: type: string description: |- A date-time value as RFC3339 timestamp string. Using string because google.protobuf.Timestamp only has second precision and RFC3339 is the canonical format used throughout this API. agentsV1TransferCompleted: type: object properties: transfer_id: type: string description: The transfer_id of the matching TransferRequested. to: type: string description: The agent that received control. initiated_by: $ref: "#/components/schemas/agentsV1TransferInitiator" description: |- A requested transfer was enacted; the target agent is now active. The active agent and the derived transfer stack are recomputed by folding these over the log; there is no `from` (it is always the prior top). agentsV1InterruptOption: type: object properties: label: type: string description: Display text for this option (1-5 words). description: type: string description: Explanation of what this option means. description: A question option for the user to select. agentsV1LiteralStringType: type: object properties: value: type: string description: The constant string value. description: A literal string constant. agentsV1EventsDeleted: type: object properties: from_event_id: type: string format: uint64 description: First event id of the deleted range (inclusive). to_event_id: type: string format: uint64 description: Last event id of the deleted range (inclusive). description: |- Notification that a contiguous range of events was deleted. The deletion is a soft-delete: the events remain retrievable with include_deleted, the same deletion the DeleteEvent RPC performs. Example triggers are the generation loop rolling a turn back and rebuilding it — the offload-and-retry rebuild, or RetryDriver between attempts. It carries no event id of its own and is broadcast purely so live clients can drop the range from their visible view (and flag it deleted in their include_deleted view) the way they reconcile a manual delete. On reload the server already excludes the range. agentsV1ToolCallArgument: type: object properties: index: type: integer format: int32 description: Index of the tool call this belongs to. name: type: string description: Argument name (the JSON key). value: $ref: "#/components/schemas/agentsV1Value" description: |- A single named argument for a tool call. Each event carries one complete argument (name + typed value). Generators emit one event per argument as each top-level key-value pair is parsed from the streaming JSON. agentsV1ObjectValue: type: object properties: fields: type: object additionalProperties: $ref: "#/components/schemas/agentsV1Value" description: A structured object with named fields. agentsV1SleepFailed: type: object properties: sleep_id: type: string description: Equal to the sleep_id of the matching SleepRequested. message: type: string description: |- Human-readable reason the sleep was rejected; rendered into the error tool-result body the model sees. description: |- A requested sleep was rejected and will never complete. Terminal for the matching SleepRequested, the failure counterpart to SleepCompleted. Currently emitted when a sub-agent calls sleep (delegates cannot suspend on time; the parent owns time-based pauses). agentsV1TransferInitiator: type: string enum: - TRANSFER_INITIATOR_UNSPECIFIED - TRANSFER_INITIATOR_AGENT - TRANSFER_INITIATOR_USER default: TRANSFER_INITIATOR_UNSPECIFIED description: Who initiated a transfer. agentsV1SubAgentOrigin: type: object properties: parent_agent_id: type: string description: |- The agent that issued the delegation (the caller). The sub-thread lives under a different agent, so the parent agent id is qualified. parent_thread_id: type: string description: The caller's thread that issued the delegation. task_id: type: string description: The delegation task/call id the sub-thread id was derived from. description: A thread created because a parent agent delegated to a sub-agent. agentsV1EmptyType: type: object description: Empty placeholder for simple types that have no additional configuration. agentsV1ContextItem: type: object properties: id: type: string description: Unique identifier for the context item. readOnly: true label: type: string description: Human-readable label for display. readOnly: true token_count: type: integer format: int64 description: Number of tokens this item consumes. readOnly: true category: $ref: "#/components/schemas/agentsV1ContextCategory" memory_block: $ref: "#/components/schemas/agentsV1MemoryBlockRef" tool: $ref: "#/components/schemas/agentsV1ToolRef" description: A single item contributing to the thread's context window. agentsV1NullValue: type: object description: Placeholder for null values (oneof requires a message type). agentsV1Usage: type: object properties: prompt_tokens: type: integer format: int32 description: Number of tokens in the prompt. completion_tokens: type: integer format: int32 description: Number of tokens in the completion. total_tokens: type: integer format: int32 description: Total number of tokens used (prompt + completion). cache: $ref: "#/components/schemas/agentsV1CacheUsage" description: Token usage statistics for a generation request. agentsV1EnumType: type: object properties: variants: type: array items: $ref: "#/components/schemas/agentsV1ValueTypeDescriptor" description: The possible variant types. description: |- A union/enum type with multiple possible variants. Always normalised on construction: at least two variants, distinct under structural equality, no nested enums, no `Any` member (`Any` absorbs every enum), and `Null` is canonicalised into `OptionalType` rather than appearing as a member. agentsV1ObjectType: type: object properties: properties: type: array items: $ref: "#/components/schemas/agentsV1ObjectPropertyDescriptor" description: The properties of the object. description: A structured object type with named properties. agentsV1ListValue: type: object properties: values: type: array items: $ref: "#/components/schemas/agentsV1Value" description: A list of values. agentsV1DictionaryType: type: object properties: keys: $ref: "#/components/schemas/agentsV1ValueTypeDescriptor" values: $ref: "#/components/schemas/agentsV1ValueTypeDescriptor" description: A dictionary/map type. agentsV1ModelInfo: type: object properties: model_id: type: string description: Model identifier (e.g., "gpt-4o", "claude-3-opus"). readOnly: true max_context_tokens: type: integer format: int64 description: Maximum context length in tokens. readOnly: true max_output_tokens: type: integer format: int64 description: Maximum output tokens. readOnly: true supports_vision: type: boolean description: Whether the model supports vision/images. readOnly: true supports_tools: type: boolean description: Whether the model supports tool/function calling. readOnly: true supports_structured_output: type: boolean description: Whether the model supports structured output (JSON mode). readOnly: true supports_streaming: type: boolean description: Whether the model supports streaming responses. readOnly: true supports_reasoning: type: boolean description: Whether the model supports reasoning (chain-of-thought). readOnly: true display_name: type: string description: Human-readable display name (e.g., "GPT-4o", "Claude Sonnet 4.5"). readOnly: true family: type: string description: Model family grouping (e.g., "gpt-4o", "claude-4.5", "qwen2"). readOnly: true license: type: string description: License information (e.g., for open-weight models). readOnly: true parameter_count: type: string format: uint64 description: Number of model parameters. readOnly: true quantization: type: string description: Quantization level (e.g., "Q4_K_M", "Q8_0"). readOnly: true supports_documents: type: boolean description: Whether the model supports document inputs (PDFs, text files). readOnly: true max_inline_artifact_bytes: type: string format: uint64 description: |- Maximum size of a single tool result that can be inlined into a generation request, in raw bytes. Already accounts for base64 expansion and a safety margin for request overhead. readOnly: true deprecated: type: boolean description: "Whether the model is deprecated: still usable, but slated for retirement." readOnly: true retired: type: boolean description: |- Whether the model is retired: loadable (so existing threads/agents don't break) but generation is refused. readOnly: true replacement_model: type: string description: Recommended replacement model id when deprecated or retired. readOnly: true pricing: $ref: "#/components/schemas/agentsV1ModelPricing" description: Information about a model and its capabilities. agentsV1ArtifactValueType: type: object properties: mime_types: type: array items: type: string description: |- Accepted MIME types (e.g., "text/csv", "application/vnd.apache.parquet"). Empty means any MIME type is accepted. description: An artifact or artifact URI value type with optional MIME type constraints. agentsV1GenerationErrorKind: type: string enum: - GENERATION_ERROR_KIND_UNSPECIFIED - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG - GENERATION_ERROR_KIND_PROVIDER_ERROR - GENERATION_ERROR_KIND_API_ERROR - GENERATION_ERROR_KIND_CONTENT_FILTERED - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED - GENERATION_ERROR_KIND_INVALID_REQUEST - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED - GENERATION_ERROR_KIND_SERIALIZATION_ERROR - GENERATION_ERROR_KIND_STREAM_ERROR - GENERATION_ERROR_KIND_CONFIGURATION_ERROR - GENERATION_ERROR_KIND_INTERNAL_ERROR - GENERATION_ERROR_KIND_STOPPED - GENERATION_ERROR_KIND_SHUTDOWN - GENERATION_ERROR_KIND_AUTHENTICATION - GENERATION_ERROR_KIND_OVERLOADED - GENERATION_ERROR_KIND_STREAM_DROPPED - GENERATION_ERROR_KIND_LOST - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE default: GENERATION_ERROR_KIND_UNSPECIFIED description: |- Error kind for generation failures. - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind. - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit. - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error. - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider. - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies. - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit. - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid. - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded. - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data. - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming. - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid. - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error. - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system. - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down. - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials). - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable. - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop). Distinct from STREAM_ERROR (transient transport blips that may succeed on retry): once partial tokens have been delivered to the user, retrying produces a different response that won't align with what's already shown. Non-retryable by classification. - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died mid-turn, and the failure was synthesized afterwards to close out the dangling thread tail. Distinct from STOPPED (a user action) and from provider errors — nothing was wrong with the request. - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g. Bedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG (a token-window overflow). Recoverable by offloading large tool results out of context and retrying. agentsV1QueuePriority: type: string enum: - QUEUE_PRIORITY_UNSPECIFIED - QUEUE_PRIORITY_TURN_WORK - QUEUE_PRIORITY_TRANSFER - QUEUE_PRIORITY_USER_INPUT default: QUEUE_PRIORITY_UNSPECIFIED description: |- Structural drain priority of a queued group (lower drains first). - QUEUE_PRIORITY_TURN_WORK: Deferred turn work: remote tool calls, control events, sub-agent tasks. - QUEUE_PRIORITY_TRANSFER: A transfer request; lands after the rest of the turn. - QUEUE_PRIORITY_USER_INPUT: A parked user message; drains after the whole turn. agentsV1PrincipalKind: type: string enum: - PRINCIPAL_KIND_UNSPECIFIED - PRINCIPAL_KIND_USER - PRINCIPAL_KIND_SERVICE - PRINCIPAL_KIND_SYSTEM default: PRINCIPAL_KIND_UNSPECIFIED description: |- Categorises a Principal by its origin. Used in audit attribution to distinguish a real end user from a machine-to-machine caller, and from internal components that mutate state without any user on whose behalf they are acting. - PRINCIPAL_KIND_USER: Authenticated end user. - PRINCIPAL_KIND_SERVICE: Non-human caller (machine-to-machine token, CI job). - PRINCIPAL_KIND_SYSTEM: Internal component (scheduler orphan sweep, backfill, etc.). agentsV1OptionalType: type: object properties: inner: $ref: "#/components/schemas/agentsV1ValueTypeDescriptor" description: An optional value type. agentsV1ChangeType: type: string enum: - CHANGE_TYPE_UNSPECIFIED - CHANGE_TYPE_ADDED - CHANGE_TYPE_MODIFIED - CHANGE_TYPE_DELETED default: CHANGE_TYPE_UNSPECIFIED description: |- Type of change for a staged artifact. - CHANGE_TYPE_UNSPECIFIED: Unspecified change type. - CHANGE_TYPE_ADDED: Artifact was added. - CHANGE_TYPE_MODIFIED: Artifact was modified. - CHANGE_TYPE_DELETED: Artifact was deleted. agentsV1ContextCategory: type: string enum: - CONTEXT_CATEGORY_UNSPECIFIED - CONTEXT_CATEGORY_FIXED - CONTEXT_CATEGORY_VOLATILE - CONTEXT_CATEGORY_COMPACTABLE default: CONTEXT_CATEGORY_UNSPECIFIED description: |- Category of context items for token budget management. - CONTEXT_CATEGORY_UNSPECIFIED: Unspecified category. - CONTEXT_CATEGORY_FIXED: Fixed context that cannot be modified (agent-scoped immutable memory + tools). - CONTEXT_CATEGORY_VOLATILE: Volatile context that can be modified (mutable memory blocks). - CONTEXT_CATEGORY_COMPACTABLE: Compactable context that can be summarized (conversation history). agentsV1ListType: type: object properties: items: $ref: "#/components/schemas/agentsV1ValueTypeDescriptor" description: A list/array type. agentsV1MemoryBlockRef: type: object properties: block_id: type: string description: The unique block identifier (deterministic hash of block name). readOnly: true type: type: string description: The block type (e.g., "text"). readOnly: true display_name: type: string description: Human-readable label for the block type. readOnly: true description: type: string description: Description of the memory block. readOnly: true scope: $ref: "#/components/schemas/agentsV1ScopeLevel" mutable: type: boolean description: Whether the block is mutable. readOnly: true description: |- Lightweight memory block reference for context items. Contains only metadata needed for context window visualization. Intentionally omits content and config to keep responses lightweight. agentsV1ToolRef: type: object properties: id: type: string description: Stable tool identifier (hash of the original tool name). readOnly: true name: type: string description: The tool name (may be adapted name if adapters are applied). readOnly: true description: type: string description: Human-readable description of what the tool does. readOnly: true source_id: type: string description: The source that provides this tool. readOnly: true is_adapted: type: boolean description: Whether this tool has been adapted. readOnly: true original_name: type: string description: The original tool name (before any adaptations). readOnly: true description: |- Lightweight tool reference for context items. Contains only metadata needed for context window visualization. Intentionally omits parameters_schema to keep responses lightweight. agentsV1ObjectPropertyDescriptor: type: object properties: name: type: string description: The property name. value_type: $ref: "#/components/schemas/agentsV1ValueTypeDescriptor" required: type: boolean description: Whether this property is required. description: A named property within an object type. agentsV1CacheUsage: type: object properties: read_tokens: type: integer format: int64 description: Tokens served from cache on this request. write_tokens: type: array items: $ref: "#/components/schemas/agentsV1CacheWrite" description: |- Tokens written to cache on this request, bucketed by TTL. Empty for providers without explicit write accounting. description: Prompt cache usage on a single generation request. agentsV1ModelPricing: type: object properties: rows: type: array items: $ref: "#/components/schemas/agentsV1DatedRates" description: |- Effective-dated rate rows. Windows should not overlap; if they do, the earliest-starting matching row wins so the outcome is deterministic. readOnly: true description: |- Complete pricing knowledge for one model: its effective-dated rate rows. An empty `rows` list is a valid "priced at zero" card for local models — distinct from a model carrying no `ModelPricing` at all, which means its cost is unknown, not free. agentsV1ScopeLevel: type: string enum: - SCOPE_LEVEL_UNSPECIFIED - SCOPE_LEVEL_AGENT - SCOPE_LEVEL_THREAD - SCOPE_LEVEL_USER default: SCOPE_LEVEL_UNSPECIFIED description: |- The scope level for a memory block's content storage. - SCOPE_LEVEL_UNSPECIFIED: Unspecified scope (defaults to AGENT). - SCOPE_LEVEL_AGENT: Agent-wide scope. Content is shared across all threads. - SCOPE_LEVEL_THREAD: Thread-local scope. Each thread has its own copy of the content. - SCOPE_LEVEL_USER: User-local scope. Each signed-in user has their own copy of the content, which follows them across all of their threads with the agent and is invisible to other users. Only kinds whose allowed_scopes include it (or list no restriction) accept it. agentsV1CacheWrite: type: object properties: tokens: type: integer format: int64 description: Number of tokens written into this bucket. ttl_seconds: type: integer format: int64 description: TTL in seconds for the written bucket (provider-specific interpretation). description: A single cache-write bucket — tokens written at a given TTL. agentsV1DatedRates: type: object properties: effective_from: type: string format: date-time description: Inclusive start of this row's validity. Absent = open-ended past. readOnly: true effective_until: type: string format: date-time description: Exclusive end of this row's validity. Absent = open-ended future. readOnly: true base: $ref: "#/components/schemas/agentsV1RateCard" tiers: type: array items: $ref: "#/components/schemas/agentsV1TierRates" description: |- Long-context tiers: token-threshold bands above `base`, ascending by `threshold_tokens`. Empty = flat pricing. A request's total prompt size selects the highest tier whose threshold it reaches, or `base` below every threshold. readOnly: true description: |- One effective-dated pricing row: the rates in force during a validity window. A model whose price changes on a schedule carries several rows differing only in rates and effective bounds. agentsV1RateCard: type: object properties: input_per_mtok: type: number format: double description: Fresh (uncached) input, USD per million tokens. readOnly: true output_per_mtok: type: number format: double description: Output, USD per million tokens. Includes reasoning/thinking tokens. readOnly: true cache_read_per_mtok: type: number format: double description: Tokens served from cache, USD per million tokens. readOnly: true cache_write_per_mtok: type: number format: double description: |- Cache writes at any TTL, USD per million tokens — for providers with a single write rate regardless of TTL. readOnly: true cache_write_by_ttl: type: array items: $ref: "#/components/schemas/agentsV1CacheWriteRate" description: Per-TTL cache-write overrides, consulted before `cache_write_per_mtok`. readOnly: true description: |- One complete set of USD-per-million-token rates. A missing cache rate is not zero — it means the dimension is unpublished, and cost computation falls back loudly (billed at the fresh-input rate, flagged estimated). agentsV1CacheWriteRate: type: object properties: ttl_seconds: type: integer format: int64 description: |- TTL in seconds this rate applies to (e.g. 300 for a 5-minute bucket, 3600 for a 1-hour bucket). readOnly: true per_mtok: type: number format: double description: USD per million tokens written into this bucket. readOnly: true description: USD rate for cache writes at one specific TTL bucket. agentsV1TierRates: type: object properties: threshold_tokens: type: integer format: int64 description: |- Prompt-size threshold (total prompt tokens: fresh + cache read + cache write) at which these rates activate. readOnly: true card: $ref: "#/components/schemas/agentsV1RateCard" description: |- One long-context tier band: requests whose total prompt tokens meet or exceed `threshold_tokens` (and fall below the next tier's threshold, when one exists) bill the entire request — every class, input and output — at `card` instead of the base card. v1BatchDeleteCollectionRowsResponse: type: object properties: deleted_count: type: string format: int64 description: Number of rows deleted. readOnly: true description: Response for BatchDeleteCollectionRows. AssetFolderServiceBatchDeleteFoldersBody: type: object properties: names: type: array items: type: string title: |- Resource names of the folders to delete. Max 100 per request. Format: organizations/{organization}/workspaces/{workspace}/folders/{folder} force: type: boolean description: |- If true, recursively delete all sub-folders and assets within each folder. If false (default), a folder with contents results in FAILED_PRECONDITION for that item. description: |- ============================================================= AssetFolderService — batch request messages (ENG-3815) ============================================================= Request to delete multiple folders in a single best-effort call. Each folder is deleted independently; failures are recorded per-item. required: - names v1SkipExceptionsResponse: type: object description: Response for skipping exceptions; no body. SecretServiceUpdateSecretBody: type: object properties: secret: $ref: "#/components/schemas/v1Secret" etag: type: string AssetServiceCreateAssetBody: type: object properties: asset: $ref: "#/components/schemas/v1Asset" file_name: type: string title: |- Resource name of the already-uploaded Bishop file. Obtained from FilesHttpService.UploadFile response. Format: organizations/{organization}/files/{file} description: |- ============================================================= AssetService request messages ============================================================= Request to register a new asset. Upload flow (2-step): 1. Client uploads the file via the existing Bishop file upload service (FilesHttpService.UploadFile) and receives a file resource name. 2. Client calls CreateAsset with that file_name and the desired metadata. The Asset Service records the workspace + folder context and tag metadata in PostgreSQL and links them to the already-uploaded Bishop file. required: - asset - file_name AssetServiceBatchDeleteAssetsBody: type: object properties: names: type: array items: type: string title: |- Resource names of the assets to delete. Max 100 per request. Format: organizations/{organization}/workspaces/{workspace}/assets/{asset} description: |- ============================================================= AssetService — batch request messages (ENG-3815) ============================================================= Request to delete multiple assets in a single best-effort call. Each asset is deleted independently; failures are recorded per-item. required: - names v1Guide: type: object properties: name: type: string description: The guide's resource name. work_item: type: string description: |- Persistent item this guidance belongs to, in the same workspace. Required on creation and immutable. Rekey does not move or copy guides. scope: type: string description: |- Free-text applicability conditions interpreted by the consuming agent. Empty means no additional conditions beyond belonging to this item. state: $ref: "#/components/schemas/v1GuideState" title: type: string description: Short title for discovery and display. body: type: string description: Free-text resolution instructions. Interpretation belongs to the reader. examples: type: array items: $ref: "#/components/schemas/v1GuideExample" description: |- Supporting units, with optional explanations. Updating this field replaces the entire list; referenced units are never modified or deleted. etag: type: string description: |- Server-issued concurrency token. Ignored on creation; required on update. Supply the current value without including etag in update_mask. A successful change rotates it; a mismatch returns ABORTED. sources: type: array items: $ref: "#/components/schemas/v1GuideSource" description: Read-only reference sources in the same workspace. Updating replaces the list. created_by: type: string title: |- Who wrote it, and who last changed it. Who changed it before that is an audit trail and belongs to vigil. Format: users/{user_id} readOnly: true updated_by: type: string title: "Format: users/{user_id}" readOnly: true create_time: type: string format: date-time description: The time the guide was written. readOnly: true update_time: type: string format: date-time description: The time it last changed. readOnly: true description: |- Guide is advisory text for people and agents resolving a class of work. Multiple guides may belong to one persistent item. The consuming agent interprets scope and instructions and enforces the state contract. Workbench never executes guidance, accepts input or submits an answer on its own. required: - work_item - title - body v1InsertCollectionRowResponse: type: object properties: row: type: object additionalProperties: $ref: "#/components/schemas/commonv1Value" description: The inserted row data. Includes the server-assigned `__row_id__`. readOnly: true description: |- Response for InsertCollectionRow. Returns the inserted row with its server-assigned __row_id__. v1GuideExample: type: object properties: work_unit: type: string description: |- Full resource name of any existing unit in the Guide's workspace, including unresolved units and units belonging to other items. Validated on save; a unit from another workspace is rejected. The reference remains stable across rekey. The Guide's own work_item association is unchanged. explanation: type: string description: Why this unit supports the instructions; no copied evidence or answer. description: GuideExample links guidance to an existing supporting work unit. required: - work_unit v1BatchDownloadAssetsResponse: type: object properties: archive_uri: type: string description: |- Presigned URL for the generated ZIP archive. Valid for `expire_duration` (default 15 minutes). readOnly: true results: type: array items: $ref: "#/components/schemas/v1BatchItemResult" description: |- Per-item results for assets that could not be included in the archive. Items with OK status were successfully added. Items with non-OK status were skipped; their names are still returned here for client awareness. readOnly: true description: |- Response for BatchDownloadAssets. The server builds a ZIP of all successfully resolved assets and returns a single presigned URL for the archive. v1UpdateCollectionRowResponse: type: object properties: row: type: object additionalProperties: $ref: "#/components/schemas/commonv1Value" description: The updated row data. Includes `__row_id__`. readOnly: true description: |- Response for UpdateCollectionRow. Returns the updated row. CollectionsServiceUpdateCollectionSchemaBody: type: object properties: schema: $ref: "#/components/schemas/v1CollectionSchema" description: Request to replace a collection's whole schema. required: - schema LibraryServiceUpdateWorkspaceBookConnectionTriggerInstanceBody: type: object properties: name: type: string title: The name of the trigger instance (required for PUT semantics) configuration: type: object additionalProperties: $ref: "#/components/schemas/bdkv2Value" description: |- Configuration parameters for the trigger (required for PUT semantics). Empty map clears the configuration. filter_expression: $ref: "#/components/schemas/bdkv2Expression" v1ImportAutomationResponse: type: object properties: automation: $ref: "#/components/schemas/v1Automation" description: Response message for ImportAutomation. v1OAuthApp: type: object properties: id: type: string description: Server-generated nanoid; what `Secret.oauth_app_id` binds to. name: type: string description: |- Slug unique within `scope`, frozen at create — there is no rename. It is the app's path segment in the credential store. display_name: type: string description: Required on create (server rejects empty). scope: type: string description: "`shared`, or `organizations/{org}[/workspaces/{ws}]`." metadata: type: object additionalProperties: type: string description: |- Free-form, extensible key/value metadata — e.g. a description, a link to the app's provider-console page, an owner. Not interpreted by the server; stored as-is and returned on read. Add new keys without a schema change. config: $ref: "#/components/schemas/v1OAuthConfig" credentials: $ref: "#/components/schemas/v1OAuthAppCredentials" create_time: type: string format: date-time etag: type: string description: Optimistic-concurrency token; send it back on `UpdateOAuthApp`. secret_type: type: string description: |- Name of the `SecretType` this app's connections use. Required on create; an app without one (created before this field) can have it set once via `UpdateOAuthApp`, after which it is immutable. bdkv1TestConnectionResponse: type: object CollectionsServiceAddCollectionFieldBody: type: object properties: field: $ref: "#/components/schemas/v1CollectionField" description: |- Request to add a new field (column) to a collection's schema. Creates a new schema version and increments the schema_version counter. required: - field AutomationServiceRestoreAutomationBody: type: object properties: revision_id: type: string description: |- The revision ID (semantic version) to restore to (e.g., "1.0", "2.0"). This must be a valid published version that exists in the automation's revision history. description: RestoreAutomationRequest specifies which automation to restore and to which version. required: - revision_id AssetServiceMoveAssetBody: type: object properties: destination_folder_name: type: string title: |- Destination folder resource name. Empty string means workspace root. Format: organizations/{organization}/workspaces/{workspace}/folders/{folder} description: Request to move an asset to a different folder (or to the workspace root). v1GetCollectionRowResponse: type: object properties: row: type: object additionalProperties: $ref: "#/components/schemas/commonv1Value" description: |- The row data. Keys are column names (including `__row_id__`); values are typed `common.v1.Value`s. readOnly: true description: |- Response for GetCollectionRow. A single row keyed by column name. v1SetMarkedOutputsResponse: type: object properties: automation: $ref: "#/components/schemas/v1Automation" description: Response containing the automation after setting a marked output. ExceptionManagerServiceUnarchiveExceptionsBody: type: object properties: filter: type: string title: |- Filter to apply before unarchiving. Filter is required as a safeguard to prevent unarchiving ALL exceptions in workspace. Only ARCHIVED exceptions matching the filter will be unarchived and transitioned to PENDING state. Non-ARCHIVED exceptions are ignored by the implementation. Allowed fields: run, automation, create_time, group Example: "automation = my-automation-id" - Unarchives archived exceptions for an automation Example: "group = my-group-id AND create_time < \"2025-01-01T00:00:00Z\"" - Unarchives old archived exceptions in my-group-id group Example: "run = run1_id OR run = run2_id" - Unarchives archived exceptions for multiple runs description: Request to unarchive exceptions. required: - filter AutomationServiceValidateAutomationPublishBody: type: object description: ValidateAutomationPublishRequest validates if an automation can be published. AuditServiceExportAuditEventsBody: type: object properties: filter: type: string description: |- An AIP-160 filter expression scoping the export (same grammar as ListAuditEvents). If empty, all events for the Organization are exported. format: $ref: "#/components/schemas/v1ExportFormat" description: Request message for ExportAuditEvents. AutomationServicePublishAutomationBody: type: object properties: resolved_placeholder_test_credentials: type: array items: $ref: "#/components/schemas/v1CredentialInfo" description: |- Connections with resolved placeholder test credentials. These connections have test credentials that have been resolved to actual credentials. description: PublishAutomationRequest contains the automation and credentials needed to publish. required: - resolved_placeholder_test_credentials AutomationImportExportServiceImportAutomationBody: type: object properties: zip_resource: type: string description: |- Bishop resource name of the ZIP bundle to import. Format: organizations/{organization}/workspaces/{workspace}/files/{name} The caller obtains this by uploading the exported bundle to Bishop in the target workspace; it is not a download URL. description: Request message for ImportAutomation. required: - zip_resource AutomationServiceRenameAutomationBody: type: object properties: display_name: type: string description: The new display name for the automation. description: |- RenameAutomationRequest contains the new display name for an automation. This operation does not affect the automation version. required: - display_name WorkItemServiceSetWorkItemInputFormBody: type: object properties: input_form: $ref: "#/components/schemas/v1FormSpec" etag: type: string description: Current WorkItem.input_form_etag, including for the first form. description: SetWorkItemInputFormRequest supplies the complete human-input form. required: - input_form - etag v1CollectionField: type: object properties: name: type: string description: The field (column) name. Must be unique within the collection schema. description: type: string description: Optional human-readable description of the field. type: $ref: "#/components/schemas/v1ValueType" required: type: boolean description: Whether a value for this field is required on every row. unique: type: boolean description: Whether values for this field must be unique across all rows. default_value: $ref: "#/components/schemas/commonv1Value" description: |- A single field (column) definition within a collection's schema. Carries the full set of editable per-field metadata used by the field-level schema editing RPCs (AddCollectionField, UpdateCollectionField, DeleteCollectionField) and surfaced on reads via CollectionSchema.fields. required: - name v1ActivateTriggerResponse: type: object properties: automation_trigger: $ref: "#/components/schemas/v1AutomationTrigger" description: Response containing the activated trigger. LibraryServiceAddWorkspaceBookConnectionAgentTriggerInstanceBody: type: object properties: trigger_id: type: string title: The name of the trigger configuration: type: object additionalProperties: $ref: "#/components/schemas/bdkv2Value" title: Configuration parameters for the trigger filter_expression: $ref: "#/components/schemas/bdkv2Expression" name: type: string title: The name of the agent trigger instance agent_ids: type: array items: type: string description: |- Identifiers of the rain agents to invoke when the trigger fires. Each agent gets its own thread and message; the prompt is sent to all. prompt: type: string title: Literal prompt sent to the rain agent as the user message v1Secret: type: object properties: id: type: string description: Server-generated nanoid; the only key RPCs address a secret by. name: type: string description: |- Slug unique within `scope`, frozen at create — there is no rename. It is the secret's path segment in the backing store. display_name: type: string description: Required on create and adopt. Mutable. scope: type: string description: "`shared`, or `organizations/{org}[/workspaces/{ws}]`." secret_type: type: string description: |- Name of the `SecretType` declaring this secret's payload schema (e.g. `postgres-creds`). Required on create, immutable thereafter. oauth_app_id: type: string description: |- `OAuthApp.id` this connection authorizes against — the app to bind to on `CreateSecret`; echoed back on read. Empty for non-OAuth secrets. state: $ref: "#/components/schemas/v1SecretState" labels: type: object additionalProperties: type: string expires_at: type: string format: date-time description: |- OAuth connections: when the access token expires, kept current by every refresh. Unset when the token can't be renewed. current_version: type: integer format: int64 etag: type: string create_time: type: string format: date-time update_time: type: string format: date-time description: |- A managed secret's metadata. Payload bytes are accessed separately via `AccessSecretVersion`; this message is metadata-only. v1ListGuideApplicationsResponse: type: object properties: guide_applications: type: array items: $ref: "#/components/schemas/v1GuideApplication" title: The guide applications 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 `ListGuideApplications` to continue listing results. Will be empty when there are no more results. total_size: type: integer format: int32 description: |- The total number of applications across all pages. This count is not affected by page_size or page_token parameters. title: Response to a list guide applications request bdkv2Value: type: object properties: null_value: type: string conceptual_value: $ref: "#/components/schemas/bdkv2NounPhrase" text_value: type: string title: "deprecated: use offloadable_text_value (15) for new code" number_value: type: number format: double boolean_value: type: boolean datetime_value: type: string format: date-time date_value: $ref: "#/components/schemas/bdkv2Date" time_value: $ref: "#/components/schemas/bdkv2Time" file_value: $ref: "#/components/schemas/bdkv2FileValue" dictionary_value: $ref: "#/components/schemas/bdkv2DictionaryValue" list_value: $ref: "#/components/schemas/bdkv2ListValue" opaque_value: $ref: "#/components/schemas/bdkv2OpaqueValue" table_value: $ref: "#/components/schemas/bdkv2TableValue" sensitive_value: $ref: "#/components/schemas/bdkv2SensitiveValue" offloadable_text_value: $ref: "#/components/schemas/v2OffloadableTextValue" offloadable_dictionary_value: $ref: "#/components/schemas/v2OffloadableDictionaryValue" offloadable_list_value: $ref: "#/components/schemas/v2OffloadableListValue" title: A union of all possible values LibraryServiceReactivateWorkspaceBookConnectionBody: type: object description: |- Request to reactivate a book connection that was scaled to zero due to inactivity. Moves the connection out of the Inactive state so the controller scales its pod back up. v1BatchDeleteFoldersResponse: type: object properties: results: type: array items: $ref: "#/components/schemas/v1BatchItemResult" description: Per-item results. Length and order match the request `names` list. readOnly: true description: |- ============================================================= AssetFolderService — batch response messages (ENG-3815) ============================================================= Response for BatchDeleteFolders. Uses BatchItemResult for best-effort per-item status. AssetServiceBatchDownloadAssetsBody: type: object properties: names: type: array items: type: string title: |- Resource names of the assets to include. Max 100 per request. Format: organizations/{organization}/workspaces/{workspace}/assets/{asset} expire_duration: type: string description: "Optional URL expiry duration for the archive download URL. Default: 15 minutes." description: |- Request to generate a presigned download URL for each of a batch of assets. Each asset produces its own presigned URL + ZIP archive entry. The server builds a ZIP archive containing all successfully resolved assets and returns a single presigned URL for the archive. required: - names v1BulkUpgradeAutomationBookConnectionsResponse: type: object properties: successful_automation_ids: type: array items: type: string description: IDs of automations whose book connections were successfully upgraded. readOnly: true failed_automations: type: array items: $ref: "#/components/schemas/v1AutomationBookConnectionUpgradeFailure" description: |- Automations that could not be upgraded, each with a reason for the failure. An automation appears here if it does not exist, is not a draft, does not contain any connection for the resolved book, or encounters any other error. readOnly: true upgraded_connections: type: array items: $ref: "#/components/schemas/v1CredentialInfo" description: |- Connection info for every connection that was newly upgraded across all successfully-upgraded automations, flattened into a single list. Each entry reflects the book, version, connection id/alias, and phase of an upgraded connection slot. readOnly: true description: BulkUpgradeAutomationBookConnectionsResponse is the response for BulkUpgradeAutomationBookConnections. v1SetExceptionGroupRoutingResponse: type: object properties: groups: type: array items: $ref: "#/components/schemas/v1ExceptionGroup" description: The updated exception groups with their routing configuration. description: Response for setting exception group routing. v1DeactivateTriggerResponse: type: object properties: automation_trigger: $ref: "#/components/schemas/v1AutomationTrigger" description: Response containing the deactivated trigger. v1BatchDuplicateFoldersResponse: type: object properties: results: type: array items: $ref: "#/components/schemas/v1BatchItemResult" description: |- Per-item results. Length and order match the request `names` list. On success, `BatchItemResult.name` is the resource name of the new root copy. readOnly: true description: Response for BatchDuplicateFolders. SubmissionServiceBatchCreateSubmissionsBody: type: object properties: work_units: type: array items: type: string description: Nonempty distinct full resource names, not IDs. Every name must belong to parent. answer: $ref: "#/components/schemas/v1Answer" work_item: type: string description: |- Expected current item of every selected unit, checked atomically on submit. Must belong to parent. Units outside this item, including itemless units, reject the entire batch. answer_draft_etags: type: object additionalProperties: type: string description: |- Supply answer or this map, exactly one. Each selected unit must have exactly one nonempty token, keyed by its full resource name. Each unit submits its own saved values. One stale, incomplete or invalid draft rejects the entire batch. Successful submission clears all selected drafts atomically. description: BatchCreateSubmissionsRequest submits a shared answer or per-unit saved drafts. required: - work_units - work_item v1FormSpec: type: object properties: fields: type: array items: $ref: "#/components/schemas/v1FormField" description: |- At least one question, with unique nonempty keys. Order is the semantic reading sequence, not a prescribed screen layout. description: |- A set of typed questions for human input or source answers (R6, R13, R14). Field types derive the returned record type. The platform selects controls and layout; there are no widgets, scripts, URLs, or executable expressions. Shared human input may reference options in each unit's immutable evidence. Workbench resolves those references into the unit's InputContext before use. Source answer forms must already be resolved. Filled values are separate messages. Sources persist their answer form with the pending invocation for recovery. required: - fields v2AddWorkspaceBookConnectionAgentTriggerInstanceResponse: type: object properties: agent_trigger_instance: $ref: "#/components/schemas/v2AgentTriggerInstance" v1PromoteParamsToCodeResponse: type: object properties: automation: $ref: "#/components/schemas/v1Automation" description: Response for PromoteParamsToCode. v2RetrieveWorkspaceAgentTriggerInstancesResponse: type: object properties: agent_trigger_instances: type: array items: $ref: "#/components/schemas/v2AgentTriggerInstance" title: The agent trigger instances v1UnsetMarkedOutputResponse: type: object properties: automation: $ref: "#/components/schemas/v1Automation" description: Response containing the automation after unsetting a marked output. v1ValidateAutomationImportResponse: type: object properties: is_imported_automation: type: boolean description: |- Whether this automation was created via import. When false, the missing_* fields are empty and no validation was performed. readOnly: true missing_connections: type: array items: $ref: "#/components/schemas/v1MissingConnection" description: Connections referenced by the automation that have no match in the workspace. readOnly: true missing_trigger_kinds: type: array items: $ref: "#/components/schemas/v1PhaseSubType" description: |- The kinds of triggers (e.g. Email, Schedule, Webhook) required by the automation's pre-phases that are not yet configured in the workspace. readOnly: true description: Response message for ValidateAutomationImport. v1ListBackendTypesResponse: type: object properties: types: type: array items: $ref: "#/components/schemas/v1BackendTypeInfo" bdkv2RetrieveTagsResponse: type: object properties: tags: type: array items: type: string title: Tags title: Response to retrieve tags v1ArchiveRunsResponse: type: object description: Response message for ArchiveRuns method. v1MoveAutomationResponse: type: object properties: automation: $ref: "#/components/schemas/v1Automation" description: Response message for MoveAutomation. v1AuditEvent: type: object properties: name: type: string title: |- The resource name of the audit event. Audit logs are org-level, so the name is always org-scoped (workspace is an attribute/filter, not part of the name). Format: organizations/{organization}/auditEvents/{audit_event} event_time: type: string format: date-time description: The time when the action occurred. readOnly: true workspace_id: type: string description: The workspace associated with the event, if any (the UI "Location"). readOnly: true category: type: string description: The broad category of the event (string name of the category enum). readOnly: true event_type: type: string description: The specific event type (string name of the event-type enum). readOnly: true action: type: string description: A free-form verb describing the action (e.g. "create", "rename"). readOnly: true actor: $ref: "#/components/schemas/v1AuditActor" resource_name: type: string description: The AIP resource name of the affected object, if any. readOnly: true before_json: type: string description: JSON snapshot of the relevant state before the change (for updates). readOnly: true after_json: type: string description: JSON snapshot of the relevant state after the change (for creates/updates). readOnly: true status: $ref: "#/components/schemas/v1AuditStatus" credits_delta: type: number format: double description: |- Signed credit delta for the event, if it affected credits (negative = consumed, positive = added). readOnly: true metadata: type: object additionalProperties: type: string description: Arbitrary additional context (e.g. source IP, integration name). readOnly: true source_service: type: string description: The service that emitted this event (e.g. "agora", "grimoire"). readOnly: true description: AuditEvent is a single recorded action in the audit log. v1AssignExceptionsResponse: type: object properties: assigned_count: type: integer format: int32 description: Number of exceptions that were assigned (or unassigned). description: Response for assigning exceptions. bdkv2TableValue: type: object properties: remote: type: string inline: $ref: "#/components/schemas/bdkv2Table" title: |- A table that is represented remote as an URL to a file that is Feather-formatted or inline via the Table message AutomationServiceForkPublishedAutomationBody: type: object description: ForkPublishedAutomationRequest specifies which automation to fork. LibraryServiceUpdateWorkspaceBookConnectionPollInstanceBody: type: object properties: name: type: string title: The name of the poll instance (required for PUT semantics) configuration: type: object additionalProperties: $ref: "#/components/schemas/bdkv2Value" description: |- Configuration parameters for the poll (required for PUT semantics). Empty map clears the configuration. filter_expression: $ref: "#/components/schemas/bdkv2Expression" poll_interval_minutes: type: integer format: int64 description: The poll interval in minutes. When absent the existing interval is preserved. v1BatchMoveAssetsResponse: type: object properties: results: type: array items: $ref: "#/components/schemas/v1BatchItemResult" description: Per-item results. Length and order match the request `names` list. readOnly: true description: Response for BatchMoveAssets. WorkItemServiceAssignWorkItemBody: type: object properties: assignee: type: string title: |- The person to assign the item to. The empty value returns it to unassigned. Format: users/{user_id} description: AssignWorkItemRequest contains the item to assign and who to assign it to. required: - assignee AutomationServiceUpgradeAutomationBookConnectionVersionBody: type: object properties: book: type: string description: |- The book whose connections should be upgraded. Must match the book field of CredentialInfo for connections to be selected. new_book_version: type: string description: |- The target book version to upgrade to. If not specified, defaults to the latest available version of the book. If specified, must be higher than the current version of the connections being upgraded. description: |- UpgradeAutomationBookConnectionVersionRequest specifies the book version transition to apply across all matching connections in a draft automation. required: - book v1ListCollectionsResponse: type: object properties: collections: type: array items: $ref: "#/components/schemas/v1Collection" description: The list of collections. readOnly: true next_page_token: type: string description: Token to retrieve the next page of results. readOnly: true total_size: type: integer format: int32 description: |- Total collections matching the request filters, across every page. Independent of `page_size` and `page_token`: paging through the collection reports the same value on each response. readOnly: true description: |- ============================================================= CollectionsService response messages ============================================================= Response for ListCollections. CollectionsServiceUpdateCollectionFieldBody: type: object properties: field_name: type: string description: |- Name of the existing field to update. To rename a field, set this to the current name, list "name" in `update_mask`, and provide the new name in `field.name`. field: $ref: "#/components/schemas/v1CollectionField" update_mask: type: string description: |- Field mask specifying which field attributes to update. Updatable paths: name, description, type, required, unique, default_value. description: |- Request to update an existing field (column) in a collection's schema. Creates a new schema version and increments the schema_version counter. required: - field_name - field v1ForkPublishedAutomationResponse: type: object properties: automation: $ref: "#/components/schemas/v1Automation" description: ForkPublishedAutomationResponse returns the updated automation with the forked draft state. bdkv2RetrieveBookResponse: type: object properties: book: $ref: "#/components/schemas/bdkv2BookDescriptor" ExceptionManagerServiceArchiveExceptionsBody: type: object properties: filter: type: string title: |- Filter to apply before archiving. Filter is required as a safeguard to prevent archiving ALL exceptions in workspace. Only PENDING exceptions matching the filter will be archived. Non-PENDING exceptions are ignored by the implementation. Allowed fields: run, automation, create_time, group Example: "automation = my-automation-id" - Archives all pending exceptions for an automation Example: "automation = my-automation-id AND create_time < \"2025-01-01T00:00:00Z\"" - Archives old pending exceptions Example: "run = run1_id OR run = run2_id" - Archives pending exceptions for multiple runs description: Request to archive exceptions. required: - filter v1ListSecretsResponse: type: object properties: secrets: type: array items: $ref: "#/components/schemas/v1Secret" next_page_token: type: string v1AddSecretVersionResponse: type: object properties: version: $ref: "#/components/schemas/v1SecretVersion" authorize_url: type: string description: |- OAuth acquisition path: the URL to send the user to for consent. Poll GetSecret until the secret leaves `pending_authorization`. WorkItemServiceSaveWorkUnitInputBody: type: object properties: values: type: object additionalProperties: $ref: "#/components/schemas/commonv1Value" description: Complete replacement map. Omitted keys are removed; empty clears all values. etag: type: string description: The input.response.etag read by the caller, never an item or form revision. description: SaveWorkUnitInputRequest replaces a unit's draft values under an etag check. required: - etag AutomationServiceDuplicateAutomationBody: type: object properties: stage: $ref: "#/components/schemas/v1AutomationStage" display_name: type: string description: |- Optional display name for the new duplicated automation. If not provided, the backend will generate a default name (e.g., "Copy of "). description: DuplicateAutomationRequest specifies which automation to duplicate and which stage to copy. required: - stage AutomationServiceSetAutomationDefaultInputsBody: type: object properties: default_inputs: type: object additionalProperties: $ref: "#/components/schemas/commonv1Value" description: |- Default input values to set. Keys are input parameter names (matching AutomationInputSpec.name). Values are the default values for those inputs. Merged with existing defaults: provided keys overwrite, null_value entries remove the key. stage: $ref: "#/components/schemas/v1AutomationStage" description: SetAutomationDefaultInputsRequest contains the default input values to set for an automation. required: - default_inputs - stage v1RestoreAutomationResponse: type: object properties: automation: $ref: "#/components/schemas/v1Automation" description: RestoreAutomationResponse returns the restored automation. ExceptionManagerServiceSetExceptionGroupRoutingBody: type: object properties: routing_rules: type: array items: $ref: "#/components/schemas/v1ExceptionGroupRoutingRule" description: |- The routing rules to set. Each rule maps a group to a default assignee. Rules for groups not included in this list are left unchanged. description: |- Request to update default assignees for exception groups in a workspace. This is an upsert operation: existing routing rules for the specified groups are updated, and new rules are created for groups that don't have one yet. required: - routing_rules v1TuneStepConfigResponse: type: object properties: config: $ref: "#/components/schemas/v1StepConfig" description: Response for TuneStepConfig. AssetServiceRefreshAssetContentBody: type: object description: Request to refresh an asset's cached content fields from its backing file. v1OAuthConfig: type: object properties: authorize_url: type: string description: |- Provider authorization endpoint. May contain `{arg}` placeholders that are filled per connection from the declared `arguments` (e.g. ".../{tenant}/oauth2/v2.0/authorize"). token_url: type: string description: |- Provider token endpoint. May contain `{arg}` placeholders, same as `authorize_url`. scopes: type: array items: type: string description: Scopes requested at authorization. extra_authorize_params: type: object additionalProperties: type: string description: |- Extra query params appended to the authorize URL — the home for provider quirks that used to be hardcoded (e.g. Google `access_type=offline`, `prompt=consent`). arguments: type: array items: $ref: "#/components/schemas/v1OAuthArgument" description: |- Per-connection template variables the endpoints reference via `{id}`. Their values are supplied at connect time (AddSecretVersion.arguments). grant_type: $ref: "#/components/schemas/v1OAuthGrantType" description: |- Declarative OAuth flow config ("recipe"). The integrations owner authors this; the engine executes it without knowing which provider it is. AutomationServiceBatchTraceCollectionUsageBody: type: object properties: collections: type: array items: type: string title: |- Collections to trace usage for; each gets one entry in the response. Format: organizations/{organization}/workspaces/{workspace}/collections/{collection} description: BatchTraceCollectionUsageRequest specifies the collections to trace usage for. required: - collections bdkv2BookDescriptor: type: object properties: id: type: string description: "@deprecated, use name and version to uniquely identify a book" title: The identifier of the book (a.k.a integration_id) name: type: string title: The name of the book short_description: type: string title: Short description of the book long_description: type: string title: Short description of the book author: type: string title: Author of the book icon: type: string format: byte title: Icon of the book in an image format that is web-compatible (i.e. JPG, PNG, SVG, WebP) version: type: string title: Version of the book authentications: type: array items: $ref: "#/components/schemas/bdkv2BookAuthenticationDescriptor" title: Authentication mechanism for a book version configurations: type: array items: $ref: "#/components/schemas/bdkv2ConceptDescriptor" title: "All the parameters available for configuring the behaviour of this book. Note: replaced by config_map" display_name: type: string title: Display name of the book endpoint: type: string title: URI location of the book, such as lambda://microsoft/1.0.4 connection_required: type: boolean description: Connection Required. True if all procedures always require a connection. discover_capable: type: boolean title: True if the book is capable of discovering book procedures tags: type: array items: type: string title: Tags associated with the book procedures: type: array items: $ref: "#/components/schemas/bdkv2BookProcedureDescriptor" title: Book procedures noun_phrase: $ref: "#/components/schemas/bdkv2NounPhrase" userinfo_capable: type: boolean title: True if the book is capable of returning oauth user's info triggers: type: array items: $ref: "#/components/schemas/v2BookTriggerDescriptor" title: Book triggers bdk_runtime_version: type: string title: BDK Runtime version environment_information: $ref: "#/components/schemas/bdkv2EnvironmentInformation" config_map: type: object additionalProperties: $ref: "#/components/schemas/bdkv2ConceptDescriptor" title: All the parameters available for configuring the behaviour of this book hidden: type: boolean title: True if the book is hidden polls: type: array items: $ref: "#/components/schemas/v2BookPollDescriptor" title: Book polls supports_remote_secret: type: boolean description: |- True if this book's runtime can resolve connection credentials from a managed secret store (referenced by credential id) instead of inline authentication values. Runtime-injected — a book gains this by running on a capable runtime. Absent/false = legacy (inline authentication only). v1ListAutomationSummariesResponse: type: object properties: automation_summaries: type: array items: $ref: "#/components/schemas/v1AutomationSummary" description: |- The list of automation summaries for the current page. May be empty if no automations match the request criteria. next_page_token: type: string description: |- A token that can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no subsequent pages. description: |- ListAutomationSummariesResponse returns a page of automation summaries and pagination information. v1TraceCollectionUsageResponse: type: object properties: automations: type: array items: $ref: "#/components/schemas/v1AutomationCollectionUsage" description: Automations that use the specified collection, with their usage type. description: TraceCollectionUsageResponse returns automations that use the specified collection. v1ListGuideEntryVersionsResponse: type: object properties: versions: type: array items: $ref: "#/components/schemas/v1GuideEntry" description: |- The versions of the guide entry, ordered newest first. Each version shares the same guide entry `name` and is distinguished by its `version` field. next_page_token: type: string description: A token to retrieve the next page of results. Empty when there are no more. total_size: type: integer format: int32 description: The total number of versions across all pages. description: Response to a list guide entry versions request. v1ValidateSecretSchemaResponse: type: object properties: valid: type: boolean description: True iff `violations` is empty. violations: type: array items: $ref: "#/components/schemas/BadRequestFieldViolation" description: |- Per-field problems (missing required, type mismatch, unknown field). Reasons are documented codes in the description, see `crate::secret_type::validator::ViolationReason`. AutomationServiceBulkUpgradeAutomationBookConnectionsBody: type: object properties: automation_ids: type: array items: type: string description: |- IDs of the draft automations in which to upgrade book connections. Each entry is an automation nano ID (not a full resource name). All specified automations must be drafts; published automations must be forked via ForkPublishedAutomation before being passed here. connection_id: type: string description: |- The ID of the new connection to apply. The book is resolved from this connection — every connection slot in each automation that belongs to the same book will be upgraded to use this connection_id, regardless of the connection's alias name. new_book_version: type: string description: |- The target book version to upgrade to. If not specified, defaults to the latest available version of the book. If specified, must be higher than the current version of the connections being upgraded. description: BulkUpgradeAutomationBookConnectionsRequest is the request for BulkUpgradeAutomationBookConnections. required: - automation_ids - connection_id v1CurrentUserResponse: type: object properties: user: $ref: "#/components/schemas/v1User" description: Response message for the `CurrentUser` method. AutomationImportExportServiceExportAutomationBody: type: object properties: revision_id: type: string description: The revision ID to export (e.g. "1.0", "0.3"). description: Request message for ExportAutomation. required: - revision_id v1AutomationKind: type: string enum: - AUTOMATION_KIND_UNSPECIFIED - AUTOMATION_KIND_QUILL - AUTOMATION_KIND_QUILL2 default: AUTOMATION_KIND_UNSPECIFIED description: |- AutomationKind identifies which builder produced an automation. This also determines how the automation's logic is represented (see per-value docs). - AUTOMATION_KIND_UNSPECIFIED: Unspecified kind. For backward compatibility, consumers MUST treat this as AUTOMATION_KIND_QUILL for legacy automations that predate this field. - AUTOMATION_KIND_QUILL: Built by the original Quill. The automation mapping to spy are defined by `input_specs` and `code_mapping`. - AUTOMATION_KIND_QUILL2: Built by Quill2 (on Rain). The automation mapping to spy is defined in an opaque "code_manifest.json" artifact; `input_specs` and `code_mapping` are not populated. v1GuideSource: type: object properties: collection: $ref: "#/components/schemas/v1GuideCollectionSource" asset: $ref: "#/components/schemas/v1GuideAssetSource" description: GuideSource identifies a resource consulted when applying a rule. v1ListAutomationRevisionSummariesResponse: type: object properties: automation_revision_summaries: type: array items: $ref: "#/components/schemas/v1AutomationRevisionSummary" description: |- The list of automation revision summaries for the current page. Revisions are ordered in reverse chronological order (newest first). next_page_token: type: string description: |- A token that can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no subsequent pages. description: |- ListAutomationRevisionSummariesResponse returns a page of automation revision summaries and pagination information. v1AutomationSummary: type: object properties: name: type: string title: |- The automation name. Format: organizations/{organization}/workspaces/{workspace}/automations/{automation} readOnly: true display_name: type: string description: Human-readable display name. readOnly: true author_id: type: string description: ID of the user who created this automation. readOnly: true latest_published_version: type: string description: |- Semantic version of the latest published version (format: major.minor). Null when there is no published version. readOnly: true update_time: type: string format: date-time description: Timestamp when the automation was last updated. readOnly: true activation_state: $ref: "#/components/schemas/v1AutomationActivationState" version: type: string description: "Current (working) semantic version (format: major.minor)." readOnly: true description: type: string description: Description of the automation's purpose. readOnly: true has_english_code: type: boolean description: |- True when the automation has English code. Exposed as a presence flag (not the full text) because the list UI only gates on its existence. readOnly: true steps: type: array items: $ref: "#/components/schemas/v1AutomationStepSummary" description: |- Ordered steps of the automation, in execution order. Projected from the automation's code manifest, which is where QUILL2 automations carry their logic — QUILL automations describe themselves through english_code instead. Empty whenever no manifest has been built for the returned version. This is a slim projection of common.v1.Step — see AutomationStepSummary. readOnly: true labels: type: array items: type: string description: User-defined labels on the automation. Ordered case-insensitively. readOnly: true description: |- AutomationSummary is a lightweight projection of Automation for list views. It intentionally omits heavy fields (code, english_code text, artifacts, code_manifest, etc.) so listing many automations stays cheap. This is a projection/view of the Automation resource, not a resource itself, so it deliberately carries no google.api.resource annotation. AutomationImportExportServiceMoveAutomationBody: type: object properties: destination_workspace: type: string title: |- The target workspace to move the automation into. May be in the same organization or a different one. Must be in the same environment as the source. Format: organizations/{organization}/workspaces/{workspace} revision_id: type: string description: The revision ID to move (e.g. "12.0", "0.3"). description: Request message for MoveAutomation. required: - destination_workspace - revision_id AssetServiceBatchDuplicateAssetsBody: type: object properties: names: type: array items: type: string title: |- Resource names of the assets to duplicate. Max 100 per request. Format: organizations/{organization}/workspaces/{workspace}/assets/{asset} destination_folder_name: type: string title: |- Optional destination folder for all copies. Empty (default) places each copy in the same folder as its original. Format: organizations/{organization}/workspaces/{workspace}/folders/{folder} description: |- Request to duplicate multiple assets in a single best-effort call. Each asset is duplicated independently; failures are recorded per-item. Copies are placed in destination_folder_name if set; otherwise each copy lands in the same folder as its original. required: - names v1CodeManifest: type: object properties: code_hash: type: string description: |- MD5 hash of the source code this manifest was generated from. Used for staleness detection against ExecutionJournal.code_hash. main: $ref: "#/components/schemas/v1MainInfo" inputs: type: array items: $ref: "#/components/schemas/v1CodeInput" description: Inputs derived from main() parameter annotations. outputs: type: array items: $ref: "#/components/schemas/v1CodeOutput" description: Outputs derived from set_output() calls via type inference. steps: type: array items: $ref: "#/components/schemas/v1Step" description: Sequential steps corresponding to user-defined function calls in main(). title: type: string description: Automation title — the first line of the module docstring. overview: type: string description: Automation overview — the remainder of the module docstring (body). description: |- CodeManifest describes the static interface, structure, and audit surface of analyzed SPy code. v2SetAutomationsForPollInstanceResponse: type: object properties: poll_instance: $ref: "#/components/schemas/v2PollInstance" TroubleshootingGuideServiceRevertGuideEntryBody: type: object properties: version: type: string description: |- The target version to revert to, in "major.minor" form (e.g. "0.3"). Must be an existing version of this guide entry. user: type: string description: |- Optional: when omitted, the new version has no attribution (the audit column is left NULL). Internal and test callers can omit it. title: |- The acting user, used by the server to attribute the new version row produced by the revert. Format: users/{user} description: Request to revert a guide entry to a previous version. required: - version v1ListFoldersResponse: type: object properties: folders: type: array items: $ref: "#/components/schemas/v1Folder" description: The list of folders. readOnly: true next_page_token: type: string description: Token to retrieve the next page of results. readOnly: true total_size: type: integer format: int32 description: |- Total folders matching the request filters, across every page. Independent of `page_size` and `page_token`: paging through the collection reports the same value on each response. readOnly: true description: |- ============================================================= AssetFolderService response messages ============================================================= Response for ListFolders. AssetFolderServiceDuplicateFolderBody: type: object properties: destination_parent_folder_name: type: string title: |- Destination parent for the duplicated folder. Empty (default) places the copy under the same parent as the original. Format: organizations/{organization}/workspaces/{workspace}/folders/{folder} description: |- Request to deep-duplicate a folder (including all descendant folders and assets). All asset files are server-side copied (object-store copy; no bytes transit the API). The root copy's display_name is prefixed "Copy of "; descendant names are unchanged. CollectionRowsServiceExportCollectionBody: type: object properties: filter: type: string description: |- AIP-160 filter expression to match rows. Deprecated: use `structured_filter` instead. order_by: type: string description: |- Comma-separated list of column names to sort by, with optional " asc" / " desc" suffix. Deprecated: use `structured_order_by` instead. expire_duration: type: string description: "Optional download URL expiry duration. Default: 1 hour." stage: $ref: "#/components/schemas/v1CollectionStage" structured_filter: $ref: "#/components/schemas/v1RowFilter" structured_order_by: type: array items: $ref: "#/components/schemas/v1SortOrder" description: "Ordering applied to matching rows. Default: `__row_id__` ascending." description: Request to export all rows of a collection as a CSV file. LibraryServiceAssociateRemoteConnectionBody: type: object properties: remote_connection_id: type: string title: The remote connection id to associate with the book connection title: Request to associate a remote connection with a book connection LibraryServiceUpgradeWorkspaceBookConnectionWithRemoteSecretBody: type: object properties: new_book_version: type: string title: The new version to upgrade book to credentials_id: type: string description: |- Existing managed credential to attach. Omit to migrate the connection's legacy secret into a new managed credential instead. description: |- Upgrade a connection onto a credential-capable book version. When `credentials_id` is set the connection is pointed at that existing managed credential; when omitted, the runtime migrates the connection's existing (legacy) secret into a new managed credential during the upgrade. CollectionsServiceCreateCollectionBody: type: object properties: collection: $ref: "#/components/schemas/v1Collection" collection_id: type: string description: Optional client-provided collection ID (UUID). schema: $ref: "#/components/schemas/v1CollectionSchema" description: |- ============================================================= CollectionsService request messages ============================================================= Request to create a collection in a workspace. required: - collection v1ArchiveExceptionsResponse: type: object properties: archived_count: type: integer format: int32 description: Number of exceptions transitioned from PENDING to ARCHIVED state. description: Response for archiving exceptions. v1AuditStatus: type: string enum: - AUDIT_STATUS_UNSPECIFIED - AUDIT_STATUS_SUCCESS - AUDIT_STATUS_FAILURE - AUDIT_STATUS_PENDING default: AUDIT_STATUS_UNSPECIFIED description: |- AuditStatus is the outcome of an audited action. - AUDIT_STATUS_UNSPECIFIED: Status is not specified. - AUDIT_STATUS_SUCCESS: The action completed successfully. - AUDIT_STATUS_FAILURE: The action failed. - AUDIT_STATUS_PENDING: The action is in progress / pending an outcome. v1BatchCreateSubmissionsResponse: type: object properties: submissions: type: array items: $ref: "#/components/schemas/v1Submission" description: Same order as request.work_units; every entry is durably accepted. description: BatchCreateSubmissionsResponse contains one immutable submission per selected unit. v1AutomationStepSummary: type: object properties: number: type: integer format: int32 description: 1-based position of the step in execution order. readOnly: true title: type: string description: Step title — the first line of the step's docstring. readOnly: true overview: type: string description: |- Step overview — the remainder of the step's docstring body, excluding the sections parsed into their own fields (Rules, Args, Returns). readOnly: true returns: type: string description: "Prose description of what the step returns (docstring Returns: section)." readOnly: true phase: type: string description: |- Phase this step belongs to, for grouping consecutive steps under a heading. Empty when the step precedes any phase marker in the automation. readOnly: true description: | AutomationStepSummary is a lightweight projection of a single common.v1.CodeManifest step, carrying only the prose a list view renders. It deliberately omits the heavy parts of common.v1.Step: the `audit` checklist (every book call, literal, and collection/asset/config access reachable from the step) and `entry_function` (the recursive call tree). Those are collected transitively across the call graph, so carrying them for every step of every automation on a page would defeat the purpose of a summary. Read the full steps from Automation.code_manifest via GetAutomation. ExceptionManagerServiceAssignExceptionsBody: type: object properties: assignee: type: string description: |- The user to assign to the exceptions. Format: users/{user} Set to "" to clear the assignment (unassign). name: type: string title: |- Assign a single exception by its full resource name. Format: organizations/{organization_id}/workspaces/{workspace_id}/exceptions/{exception_id} filter: type: string description: |- Example: "group = \"missing_values\"" - Assign all pending missing_values exceptions Example: "group = \"missing_values\" AND automation = \"auto-123\"" - Assign missing_values for a specific automation Example: "automation = \"auto-123\"" - Assign all pending exceptions for an automation title: |- Filter to select exceptions for bulk assignment. Follows Google AIP-160 filtering standard. Supported fields: group, automation, create_time, run, stage description: |- Request to assign exceptions to a user. Supports three assignment scopes via the target field: 1. Single exception: set `name` to assign one specific exception. 2. Filtered exceptions: set `filter` to assign exceptions matching AIP-160 criteria. Use this for group-level or automation-level assignment. Assignment behavior: - Only PENDING exceptions are assigned. RESOLVED/ARCHIVED exceptions are skipped. - Set `assignee` to "" to clear the assignment (unassign). - The response returns the number of exceptions that were updated. required: - assignee v1BatchItemResult: type: object properties: name: type: string title: |- Resource name of the item that was processed. For assets: organizations/{org}/workspaces/{ws}/assets/{asset} For folders: organizations/{org}/workspaces/{ws}/folders/{folder} readOnly: true status: $ref: "#/components/schemas/rpcStatus" description: |- ============================================================= Batch operation types (shared across batch RPCs) ============================================================= Per-item result for a batch (best-effort) operation. Returned in all Batch* response messages. v1WorkItem: type: object properties: name: type: string title: |- The resource name of the work item. Format: organizations/{organization_id}/workspaces/{workspace_id}/workItems/{work_item_id} kind: type: string description: |- The registered kind of work, as an opaque dotted id (for example "astral.automation_exception"). This is a string rather than an enum so that registering a kind is not a proto change. It is validated against the registered kind descriptors, so the set is closed at runtime. No behaviour in this contract branches on it. readOnly: true agg_labels: $ref: "#/components/schemas/commonv1Value" question: type: string description: |- The question in business language: the summary of the unit that materialised this item, verbatim. The pointer and source summary are fixed for the item's life. Per-unit questions remain available on the units; this is a queue summary. It is one unit's words about a set. Clients use unit_counts to show the number of occurrences relevant to their view. readOnly: true assignee: type: string title: |- The person this item is assigned to. The empty value means unassigned, which is an ordinary state of a queue and not a missing value. Format: users/{user_id} declined_by: type: string title: |- The person who last handed this item back. Current state rather than history; the history is in the audit log. Format: users/{user_id} readOnly: true decline_reason: type: string description: Why the item was last handed back. Current state rather than history. readOnly: true create_time: type: string format: date-time description: The time the item was materialised. This is the item's age. readOnly: true update_time: type: string format: date-time description: The time the item last changed. readOnly: true input_form: $ref: "#/components/schemas/v1FormSpec" input_form_etag: type: string description: |- Concurrency token for input_form, present even before the first form is set. Changes only when the form changes. Returned by Get and List. readOnly: true archive_time: type: string format: date-time description: |- When the item was explicitly archived. Absence means not archived. Unarchive clears this field. Archival locally dismisses unresolved units and future arrivals; answered and withdrawn units retain their outcomes. readOnly: true unit_counts: type: array items: $ref: "#/components/schemas/v1WorkUnitStatusCount" description: |- Counts of all attached units, independent of any ListWorkItems filter. Returned by Get and List. Exactly one entry for every defined WorkUnitStatus except UNSPECIFIED, including zero counts; no duplicate statuses. Sum all entries for the total, or selected statuses for a view's count. readOnly: true preparation_required: type: boolean description: |- Whether the UI should offer preparation before opening chat. Set for preparation-enabled kinds when unresolved membership changes from zero to nonzero, including initial arrival, unarchive and rekey. Further arrivals while unresolved units remain do not set it again. Suppress the gate when no unresolved units remain, regardless of this stored flag. MarkWorkItemPreparationStarted clears it after Rain accepts a prompt. Automatic invocation also clears it on message acceptance while its unit still belongs to the item and the item is not archived. Clearing this flag does not change unit status or indicate preparation has finished. This is not execution state or an authorization boundary. Returned by Get and List. readOnly: true revision: type: string format: int64 description: |- Monotonically increasing version of this resource's mutable state. Compare only revisions of the same resource. Includes changes to unit_counts. Independent of form and draft etags; never a mutation precondition. readOnly: true description: |- WorkItem groups related occurrences that can be resolved independently. An item is not a container a source puts things in. It is materialised by this service from the work units that share the labels the workspace groups on, so its identity is those label values. Each unit records its lifecycle independently of delivery. A submission settles one unit; delivery records whether the source applied it. One item persists for each workspace, kind and grouping identity. New units attach to the same item; archived items locally dismiss new arrivals. Existing submissions and assignment survive new arrivals. Rekey never changes this identity. bdkv2RetrieveBooksResponse: type: object properties: books: type: array items: $ref: "#/components/schemas/bdkv2BookDescriptor" title: All the books that satisfy the query next_page_token: type: string description: The token to use to retrieve the next page of books. v1ExportFormat: type: string enum: - EXPORT_FORMAT_UNSPECIFIED - EXPORT_FORMAT_CSV default: EXPORT_FORMAT_UNSPECIFIED description: |- The output format for an audit-log export. - EXPORT_FORMAT_UNSPECIFIED: Format is not specified; the server defaults to CSV. - EXPORT_FORMAT_CSV: Comma-separated values. v1ListWorkItemKindsResponse: type: object properties: work_item_kinds: type: array items: $ref: "#/components/schemas/v1WorkItemKind" description: The registered kinds, in no guaranteed order. next_page_token: type: string description: The token to retrieve the next page, or empty if this is the last. description: ListWorkItemKindsResponse contains the registered kinds. v1BuildStepHarnessResponse: type: object properties: entry_point: type: string description: The Jarvis entry-point function to invoke for the isolated single-step run. inputs: type: array items: $ref: "#/components/schemas/v1HarnessInput" description: Inputs the step run expects (from the manifest step args / recorded I/O). tunable_slots: type: array items: $ref: "#/components/schemas/v1ValueSlot" description: The value slots exposed as runtime-tunable params for the run. is_mutating: type: boolean description: |- Whether the target step performs a world-changing book call (manifest ExternalCall.is_mutating) — so the caller can gate a live run. etag: type: string description: Opaque version tag of the code the harness was built from (AIP-154). description: |- Response for BuildStepHarness. The step runs in isolation via the Jarvis single-step entry point over recorded inputs (from Bishop); this describes that run rather than synthesizing SPy. v1ExportCollectionResponse: type: object properties: download_uri: type: string description: Presigned URL to download the generated CSV file. readOnly: true description: Response for ExportCollection. v1ListGuidesResponse: type: object properties: guides: type: array items: $ref: "#/components/schemas/v1Guide" description: The guides. next_page_token: type: string description: A token to retrieve the next page, or empty if there are no more. total_size: type: integer format: int32 description: The total number matching the filter. description: ListGuidesResponse contains one page of guides. v1GuideState: type: string enum: - GUIDE_STATE_UNSPECIFIED - GUIDE_STATE_AUTO - GUIDE_STATE_REVIEW_REQUIRED - GUIDE_STATE_DISABLED default: GUIDE_STATE_UNSPECIFIED description: |- GuideState defines approval behavior for the consuming agent. Workbench stores this state; the agent enforces it. Applying any REVIEW_REQUIRED guide requires confirmation before final submission. Conflicting advice requires clarification even when all applicable guides are AUTO. No state bypasses input acceptance, caller attribution or final-submission preconditions. - GUIDE_STATE_UNSPECIFIED: Defaults to REVIEW_REQUIRED on creation; invalid when updating state. - GUIDE_STATE_AUTO: The agent may apply this guidance and submit without requesting confirmation. - GUIDE_STATE_REVIEW_REQUIRED: The agent proposes an answer and obtains confirmation before submitting. - GUIDE_STATE_DISABLED: Not used by agents. Available for management with include_disabled=true. v1OAuthAppCredentials: type: object properties: client_id: type: string client_secret: type: string description: Write-only. Stored in the managed credential store; never returned. AssetServiceDuplicateAssetBody: type: object properties: destination_folder_name: type: string title: |- Destination folder for the duplicated asset. Empty (default) places the copy in the same folder as the original. Format: organizations/{organization}/workspaces/{workspace}/folders/{folder} description: |- ============================================================= AssetService — single-item custom-method request messages (ENG-3815) ============================================================= Request to duplicate an asset. Creates a server-side file copy (object-store copy; no bytes transit the API) and registers a new asset record with display_name prefixed "Copy of ". v1Folder: type: object properties: name: type: string title: |- Server-assigned resource name. Format: organizations/{organization}/workspaces/{workspace}/folders/{folder} readOnly: true display_name: type: string description: |- Human-readable display name for this folder (e.g., "Reports 2026"). Must be unique within the same parent folder in the same workspace. parent_folder_name: type: string title: |- Resource name of the parent folder, or empty if this is a root folder. Format: organizations/{organization}/workspaces/{workspace}/folders/{folder} created_by: type: string description: ID of the user who created this folder. readOnly: true create_time: type: string format: date-time description: Timestamp when the folder was created. readOnly: true update_time: type: string format: date-time description: Timestamp when the folder was last updated (renamed or moved). readOnly: true asset_count: type: integer format: int32 description: Number of assets directly contained in this folder (non-recursive). readOnly: true folder_count: type: integer format: int32 description: Number of immediate child folders (non-recursive). readOnly: true description: |- ============================================================= Asset & Folder types ============================================================= A workspace-scoped folder for organising assets. Folders use an adjacency-list model: each folder optionally points to a parent_folder_name. A NULL parent means the folder is at the workspace root. Arbitrary nesting depth is supported. required: - display_name bdkv2Expression: type: object properties: binary_expression: $ref: "#/components/schemas/bdkv2BinaryExpression" unary_expression: $ref: "#/components/schemas/bdkv2UnaryExpression" value_expression: $ref: "#/components/schemas/bdkv2Value" noun_phrases_expression: $ref: "#/components/schemas/bdkv2NounPhrases" v1Answer: type: object properties: kind: type: string description: The registered kind this answer is for, checked against the item on submit. values: type: object additionalProperties: $ref: "#/components/schemas/commonv1Value" description: |- Exact declared field set: unknown keys fail and required omissions fail. Optional omission normalizes to None; initial suggestions are never inserted. Selection membership and normalization follow the field's InputSpec. description: |- Answer is the typed values supplied for the questions in a resolved form. Each submission validates against its own unit's source contract. required: - kind - values v1ExportAutomationResponse: type: object properties: zip_uri: type: string description: |- Presigned download URL for the exported ZIP bundle (valid ~1 hour). The caller can download the bundle directly from this URL. readOnly: true expire_time: type: string format: date-time description: Expiration time of the download URL (1 hour from creation). readOnly: true description: Response message for ExportAutomation. ExceptionManagerServiceSkipExceptionsBody: type: object properties: names: type: array items: type: string description: |- The full resource names of the exceptions to skip. Format: organizations/{organization_id}/workspaces/{workspace_id}/exceptions/{exception_id} Duplicate names may be de-duplicated by the server. description: |- Request to skip multiple exceptions in one request. Only PENDING exceptions are skipped; RESOLVED and ARCHIVED exceptions are ignored. required: - names v1DeleteAutomationTriggerResponse: type: object properties: automation_trigger: $ref: "#/components/schemas/v1AutomationTrigger" description: Response containing the deleted trigger. AgentImportExportServiceValidateAgentImportBody: type: object description: Request message for ValidateAgentImport. CollectionRowsServiceBatchInsertCollectionRowsBody: type: object properties: rows: type: array items: $ref: "#/components/schemas/v1CollectionRow" description: Rows to insert, without `__row_id__`. Max 1000 per call. stage: $ref: "#/components/schemas/v1CollectionStage" description: Request to insert multiple rows in one atomic call. required: - rows v1ListWorkspaceTagsResponse: type: object properties: tags: type: array items: type: string description: |- Deduplicated, sorted list of all tag strings in use across all assets in the workspace. Tags are deduplicated case-insensitively, so each tag appears once. Used to populate the Tags filter dropdown in the Library UI. readOnly: true description: Response for ListWorkspaceTags. AutomationServiceTuneStepConfigBody: type: object properties: stage: $ref: "#/components/schemas/v1AutomationStage" values: type: object additionalProperties: {} description: Slot values to upsert (ValueSlot.path → value). NullValue clears a key. replace: type: boolean description: |- When true, replace the whole overlay with `values` (omitted keys are cleared) rather than merging. Default false = merge/upsert. etag: type: string description: |- Optimistic concurrency: reject with ABORTED if the draft changed since this etag (from IdentifyStepValueSlots / ReadStepConfig). Empty = last-writer-wins. description: Request for TuneStepConfig. required: - stage - values bdkv2BookProcedureDescriptor: type: object properties: id: type: string title: Id of the procedure to use in subsequent calls signature: $ref: "#/components/schemas/bdkv2BookProcedureSignature" inputs: type: array items: $ref: "#/components/schemas/bdkv2ConceptDescriptor" title: All the inputs for the procedure (required and non required) outputs: type: array items: $ref: "#/components/schemas/bdkv2ConceptDescriptor" title: All the outputs for the procedure short_description: type: string title: Short description long_description: type: string title: Longer description filter_capable: type: boolean title: Can this procedure filter its response? page_capable: type: boolean title: Can this procedure page its response? connection_required: $ref: "#/components/schemas/bdkv2ConnectionRequired" is_discovered: type: boolean title: True if the procedure was discovered questions: type: array items: $ref: "#/components/schemas/bdkv2QuestionDescriptor" title: Questions the procedure may ask examples: type: array items: $ref: "#/components/schemas/bdkv2ExampleDescriptor" title: Examples of procedure usage is_async: type: boolean title: Does the procedure return a promise? is_mutation: type: boolean title: True if the procedures performs a mutating action search_hints: type: array items: type: string title: Search hints used for procedure resolution spy_signature: $ref: "#/components/schemas/v2SpySignatureDescriptor" v1RetryExceptionsResponse: type: object description: Response for retrying exceptions; no body. v1TraceAssetUsageResponse: type: object properties: automations: type: array items: $ref: "#/components/schemas/v1AutomationAssetUsage" description: Automations that reference the specified asset. description: TraceAssetUsageResponse returns automations that reference the specified asset. v1CountExceptionsByAssigneeResponse: type: object properties: assignee_counts: type: array items: $ref: "#/components/schemas/v1ExceptionAssigneeCount" description: Exception counts by assignee. next_page_token: type: string description: |- Token to retrieve the next page of results. Empty when there are no more results. total_size: type: integer format: int32 description: |- Total number of distinct assignees with exceptions (across all pages). Respects the filter from the request. Includes unassigned (null assignee) as a separate entry if applicable. total_exception_count: type: integer format: int32 description: |- Total count of all exceptions across all assignees. Respects the filter from the request. This is the sum of all counts in assignee_counts (across all pages). description: Response containing exception counts by assignee. v1ValidateAutomationPublishResponse: type: object properties: missing_prod_creds: type: array items: $ref: "#/components/schemas/v1CredentialInfo" description: |- Connections missing only production credentials. These connections have test credentials but need production credentials to publish. readOnly: true missing_test_and_prod_creds: type: array items: $ref: "#/components/schemas/v1CredentialInfo" description: |- Connections missing both test and production credentials. These connections need both credential types to be provided. readOnly: true description: ValidateAutomationPublishResponse returns validation results for publishing. v1BackendTypeInfo: type: object properties: type_id: type: string display_name: type: string description: type: string user_creatable: type: boolean description: |- false for platform-managed defaults — visible for documentation but not user-creatable via the API. config_fields: type: array items: $ref: "#/components/schemas/v1FieldSpec" description: Fields under `Backend.config`. auth_methods: type: array items: $ref: "#/components/schemas/v1AuthMethodSpec" description: Auth methods this backend supports. UI shows a dropdown. v1WorkItemKind: type: object properties: name: type: string title: |- The resource name of the kind. The final segment is exactly the opaque id carried in WorkItem.kind, which is what a client joins on. Format: workItemKinds/{kind_id} display_name: type: string description: |- The label to show a person in place of the opaque id, for example "Automation exception". readOnly: true description: type: string description: |- One sentence on what this kind of work is, for a surface that has room for it. May be empty. readOnly: true aggregation_keys: type: array items: type: string description: |- The label keys this kind groups on. Each key is optional: a unit that does not carry one groups as a null for that key rather than being rejected. Empty means one item per unit, as does a unit that carries none of these keys. Its reader is a surface explaining why two units sit on one item, which R9 requires a person to be able to see. readOnly: true dismissible: type: boolean description: |- Whether work of this kind can simply stop being asked. False when something is waiting on the answer: a suspended run needs a value or an explicit abandon, and dropping its question leaves it waiting forever. True when nothing is blocked and the question is merely a question, as for a detector's finding. ArchiveWorkItem rejects kinds that are not dismissible. Registration rejects changing true to false while any item of this kind remains archived. Retry, skip and abandon are answers rather than dismissals, because each one tells the source to do something. readOnly: true retire_time: type: string format: date-time description: |- When this kind stopped being registered. Absent while it is in effect. A retired kind is still listed, because items already created under it still need a display name. Set means no new work of this kind will arrive: its units are quarantined rather than admitted. A surface offering kinds as a filter value reads this to tell a retired kind from a quiet one. Retirement is reversible. Registering the kind again clears this. readOnly: true agent_id: type: string description: |- Workspace-scoped Rain agent ID, not a versioned Kubernetes resource name. The agent accepts organizationId, workspaceId and workItemId variables. Immutable across retirement and re-registration of the kind. Empty for existing descriptors awaiting their first explicit agent registration. readOnly: true preparation_required: type: boolean description: |- Whether work needs preparation before requesting a response. Without an item input_form, unresolved units are PROCESSING when true and WAITING_FOR_INPUT when false, ready for a direct source answer. Changes update existing unresolved units without an input_form. Published input and its acceptance govern status independently of this policy. Also arms the item's preparation prompt on zero-to-nonzero unresolved membership. Disabling clears existing prompt flags; enabling arms only future membership transitions. Neither value starts an agent or gates submission. readOnly: true description: |- WorkItemKind is a registered kind of work, as much of it as a client needs. A kind's descriptor is supplied at runtime and most of it is this service's business: where to deliver an answer, and how long to wait for the effect. What a client cannot do without is here — the label to show instead of the opaque id and which label keys group. The answer form is not here; it is declared per unit and reaches a client as WorkUnit.answer_form. Registration is a Kubernetes custom resource, not an API call, so every field is output only and there is no Create, Update or Delete. v1ListExceptionClustersResponse: type: object properties: clusters: type: array items: $ref: "#/components/schemas/v1ExceptionCluster" description: The clusters on this page, in the requested order. next_page_token: type: string description: |- Token to retrieve the next page of results. Empty when there are no more results. total_size: type: integer format: int32 description: |- Total number of distinct clusters (across all pages). Respects the filter from the request. total_exception_count: type: integer format: int32 description: |- Total count of exceptions across all clusters (across all pages). Respects the filter from the request. This is the sum of member_count over every cluster, not just the ones on this page. description: Response containing a page of exception clusters. v1Asset: type: object properties: name: type: string title: |- Server-assigned resource name. Format: organizations/{organization}/workspaces/{workspace}/assets/{asset} readOnly: true display_name: type: string description: |- Human-readable display name for this asset (e.g., "Q1 Report.pdf"). Must be unique within the same folder (or workspace root) in the workspace. description: type: string description: Optional description. folder_name: type: string description: |- Resource name of the folder this asset belongs to. Empty means the asset is at the workspace root (no folder). file_name: type: string title: |- Reference to the underlying Bishop file (org-scoped file_id). Format: organizations/{organization}/files/{file} readOnly: true mime_type: type: string description: Server-detected MIME type of the uploaded file. readOnly: true size_bytes: type: string format: int64 description: Size of the file in bytes. readOnly: true tags: type: array items: type: string description: |- Free-form string labels attached to this asset. Tags are workspace-scoped — the same string may exist on multiple assets within a workspace. A single asset may carry multiple tags. Each tag is stored as provided (trimmed of surrounding whitespace), but tags are compared case-insensitively: "Finance" and "finance" are the same tag. Duplicates by case on one asset are dropped (the first one is kept). Limits: at most 20 tags per asset; each tag 1-255 characters after trimming. Tags are updatable via UpdateAsset (include "tags" in update_mask). Use ListWorkspaceTags to enumerate all tags in use within a workspace. created_by: type: string description: ID of the user who created this asset. readOnly: true create_time: type: string format: date-time description: Timestamp when the asset was created. readOnly: true update_time: type: string format: date-time description: Timestamp when the asset was last updated (renamed, moved, description changed, or tags changed). readOnly: true reference_uri: type: string description: |- This is an opaque, stable identity handle — NOT a publicly fetchable URL. It deliberately does not embed organization/workspace: callers must resolve those from their own request context (e.g. the parent they used to look up this asset), never by parsing them out of this string. Consumers pass it through bishop-url's parser and resolve it to bytes via the authenticated Asset/File services (e.g. GenerateAssetDownloadUrl). title: |- Canonical bishop:// handle that uniquely identifies this asset's underlying file. Format: bishop://{id}--{filename} e.g. bishop://ab12cd34--report.pdf readOnly: true description: |- An asset — a workspace-scoped file reference that records human-readable name, optional folder placement, and a link to the underlying Bishop file. Asset bytes are stored in Bishop's existing file storage at the org level. The Asset Manager tracks the workspace + folder context in PostgreSQL. required: - display_name v1ListAssetsResponse: type: object properties: assets: type: array items: $ref: "#/components/schemas/v1Asset" description: The list of assets. readOnly: true next_page_token: type: string description: Token to retrieve the next page of results. readOnly: true total_size: type: integer format: int32 description: |- Total assets matching the request filters, across every page. Independent of `page_size` and `page_token`: paging through the collection reports the same value on each response. readOnly: true description: |- ============================================================= AssetService response messages ============================================================= Response for ListAssets. AutomationServiceSetAutomationLabelsBody: type: object properties: labels: type: array items: type: string description: |- The full desired label set. At most 20 labels, each 1 to 255 characters after trimming. Empty removes all labels. description: SetAutomationLabelsRequest contains the full label set for an automation. v1ValidateAgentImportResponse: type: object properties: is_imported_agent: type: boolean description: |- Whether this agent was created via import. When false, the missing_* fields are empty and no validation was performed. readOnly: true missing_connections: type: array items: $ref: "#/components/schemas/v1MissingConnection" description: |- Connections referenced by the *bundled automations'* phase code that have no match in the workspace. Reuses the automation import MissingConnection type; the phase field is prefixed with the owning automation id. These are code aliases inside the automations — see agent_connections for the connections the agent itself is wired to. readOnly: true missing_trigger_kinds: type: array items: $ref: "#/components/schemas/v1PhaseSubType" description: |- The kinds of triggers (e.g. Email, Schedule, Webhook) required by the bundled automations' pre-phases that are not yet configured in the workspace. readOnly: true warnings: type: array items: type: string description: Non-fatal warnings captured at import time (e.g. from the agent service). readOnly: true agent_connections: type: array items: $ref: "#/components/schemas/v1AgentConnection" description: |- Book connections attached to the *agent itself* through its `connection` tool sources, reported whether or not they resolve in this workspace. A separate concern from missing_connections: these come from the agent's tool catalog rather than from any automation's phase code. readOnly: true description: Response message for ValidateAgentImport. CollectionsServiceDeleteCollectionFieldBody: type: object properties: field_name: type: string description: Name of the field (column) to remove. description: |- Request to delete a field (column) from a collection's schema. Creates a new schema version and increments the schema_version counter. required: - field_name CollectionsServicePublishCollectionBody: type: object properties: published_by: type: string description: Identifier of the actor that triggered the publish. description: "Request to publish a collection: promote the draft stage to published." required: - published_by v1PublishAutomationResponse: type: object properties: published_version: type: string title: |- The semantic version of the newly published automation (format: major.minor). This corresponds to the AutomationRevision that was created. Examples: "0.1", "1.0", "2.0" readOnly: true description: PublishAutomationResponse returns the published semantic version. v1AutomationRevisionSummary: type: object properties: name: type: string description: |- The name of the automation revision. Format: organizations/{organization}/workspaces/{workspace}/automations/{automation}/revisions/{revision} The revision ID is the semantic version string (e.g., "0.1", "1.0", "2.0"). readOnly: true snapshot: $ref: "#/components/schemas/v1Automation" create_time: type: string format: date-time description: Timestamp when this revision was created. readOnly: true alternate_ids: type: array items: type: string description: |- Other revision IDs that reference the same snapshot (e.g., "latest"). Per AIP-162, this allows aliases for revisions. readOnly: true input_diff: $ref: "#/components/schemas/v1AutomationInputDiff" description: |- AutomationRevisionSummary is a lightweight projection of AutomationRevision for version-history list views. It mirrors AutomationRevision field-for-field, but its snapshot intentionally omits the heavy `code` (SPy) field and the `description` field; every other automation field is populated exactly as in AutomationRevision.snapshot. Omitting these keeps listing many revisions cheap and prevents oversized responses that fail gRPC-JSON transcoding at the API gateway. This is a projection/view of the AutomationRevision resource, not a resource itself, so it deliberately carries no google.api.resource annotation. AutomationServiceDeactivateAutomationBody: type: object description: DeactivateAutomationRequest specifies which automation to deactivate. v1DiscoverInventoryResponse: type: object properties: entries: type: array items: $ref: "#/components/schemas/v1InventoryEntry" next_page_token: type: string AssetServiceBatchMoveAssetsBody: type: object properties: names: type: array items: type: string title: |- Resource names of the assets to move. Max 100 per request. Format: organizations/{organization}/workspaces/{workspace}/assets/{asset} destination_folder_name: type: string title: |- Destination folder resource name. Empty string means workspace root. Format: organizations/{organization}/workspaces/{workspace}/folders/{folder} description: |- Request to move multiple assets to a destination folder in a single best-effort call. Each asset is moved independently; failures are recorded per-item. required: - names WorkItemServiceDeclineAssignmentBody: type: object properties: reason: type: string description: |- Why the item is being handed back. Required, because the reason is what whoever picks it up next needs. description: DeclineAssignmentRequest contains the item to hand back and why. required: - reason WorkItemServiceUnarchiveWorkItemBody: type: object description: UnarchiveWorkItemRequest contains the item to unarchive. v1GuideCollectionSource: type: object properties: name: type: string description: Full workspace-scoped collection resource name. stage: $ref: "#/components/schemas/v1CollectionStage" description: GuideCollectionSource selects a collection's operational data. required: - name - stage v1AutomationAssetUsage: type: object properties: automation_id: type: string description: |- The automation ID that references the asset. This is the automation ID portion only (e.g., the {automation} part of the resource name). display_name: type: string description: Display name of the automation (denormalized for UI convenience). description: |- AutomationAssetUsage represents an automation that references a specific asset. Assets are read-only references, so no usage type is reported. v1CollectionPreview: type: object properties: stage: $ref: "#/components/schemas/v1CollectionStage" fields: type: array items: $ref: "#/components/schemas/v1CollectionField" description: The first fields of that stage's schema, in schema order. readOnly: true rows: type: array items: $ref: "#/components/schemas/v1CollectionRow" description: |- The first rows of that stage, holding only the columns in `fields` plus `__row_id__`. Empty when the stage has no rows. readOnly: true field_count: type: integer format: int32 description: Total fields in that stage's schema; can exceed `fields`. readOnly: true record_count: type: string format: int64 description: |- Approximate total rows in that stage, with the same caveat as Collection.record_count; can exceed `rows`. readOnly: true description: |- A sample of up to 5 fields and 5 rows of a collection, taken from its published stage if it has ever been published, otherwise from its draft stage. v1Collection: type: object properties: name: type: string title: |- Server-assigned resource name. Format: organizations/{organization}/workspaces/{workspace}/collections/{collection} readOnly: true display_name: type: string description: |- Human-readable display name for this collection (e.g., "Customer Records"). Must be unique within the workspace. description: type: string description: Optional description of what this collection stores. schema_version: type: integer format: int32 description: |- Current schema version number (monotonically increasing). Schema versions start at 1 and increment with each schema edit (AddCollectionField / UpdateCollectionField / DeleteCollectionField). readOnly: true created_by: type: string description: ID of the user who created this collection. readOnly: true create_time: type: string format: date-time description: Timestamp when the collection was created. readOnly: true update_time: type: string format: date-time description: Timestamp when the collection was last updated (schema or metadata changed). readOnly: true reference_uri: type: string description: |- This is an opaque, stable identity handle resolved via the authenticated Collection service (rows are read through CollectionRowsService). title: |- Canonical bishop:// handle that uniquely identifies this collection. Format: bishop://collections/organizations/{organization}/workspaces/{workspace}/collections/{collection} readOnly: true record_count: type: string format: int64 description: |- Approximate total number of rows stored across all partitions of the collection. Derived from partition bookkeeping rather than a live scan, so it may overcount after row deletions. readOnly: true field_count: type: integer format: int32 description: |- Number of columns defined in the collection's current schema. Zero when the collection has no schema yet. readOnly: true stage: $ref: "#/components/schemas/v1CollectionStage" preview: $ref: "#/components/schemas/v1CollectionPreview" has_unpublished_changes: type: boolean description: Whether the draft schema has edits that are not yet published. readOnly: true tags: type: array items: type: string description: |- Free-form string labels attached to this collection. Tags are workspace-scoped — the same string may exist on multiple collections within a workspace. A single collection may carry multiple tags. Each tag is stored as provided (trimmed of surrounding whitespace), but tags are compared case-insensitively: "Finance" and "finance" are the same tag. Duplicates by case on one collection are dropped (the first one is kept). Limits: at most 20 tags per collection; each tag 1-255 characters after trimming. Tags may be set on CreateCollection and replaced via UpdateCollection (include "tags" in update_mask; an empty list clears all tags). Use ListCollectionTags to enumerate all tags in use within a workspace. description: |- ============================================================= Collection types ============================================================= A collection — a workspace-scoped database table with a typed schema. Collections store structured data in rows, with each row conforming to the collection's schema. The schema is versioned, allowing safe evolution over time while maintaining backward compatibility for automations. required: - display_name v1BatchMoveFoldersResponse: type: object properties: results: type: array items: $ref: "#/components/schemas/v1BatchItemResult" description: Per-item results. Length and order match the request `names` list. readOnly: true description: Response for BatchMoveFolders. v1BatchTraceCollectionUsageResponse: type: object properties: collection_usages: type: array items: $ref: "#/components/schemas/v1CollectionUsage" description: One entry per requested collection, in request order. description: BatchTraceCollectionUsageResponse returns the automations using each requested collection. v1ExceptionGroupRoutingRule: type: object properties: group: type: string description: |- The exception group identifier (e.g., "missing_values", "user_system_error"). This is the short group ID, not the fully qualified name. default_assignee: type: string description: |- The default assignee for new exceptions in this group. Format: users/{user} Set to "" to clear the default assignee (no auto-assignment for this group). description: A routing rule that maps an exception group to a default assignee. required: - group - default_assignee v1AuthMethodSpec: type: object properties: id: type: string display_name: type: string description: type: string fields: type: array items: $ref: "#/components/schemas/v1FieldSpec" description: Inputs the customer provides when picking this method. CollectionRowsServiceBatchDeleteCollectionRowsBody: type: object properties: row_ids: type: array items: type: string format: uint64 description: "`__row_id__`s of the rows to delete. Max 1000 per call." stage: $ref: "#/components/schemas/v1CollectionStage" description: Request to delete multiple rows by `__row_id__` in one atomic call. required: - row_ids v1SourceMap: type: object properties: entries: type: array items: $ref: "#/components/schemas/v1SourceMapEntry" description: List of entries mapping step labels to source locations. description: |- SourceMap contains the mapping between AOP step labels and their locations in the original SPy source code. LibraryServiceSetAutomationsForPollInstanceBody: type: object properties: automation_ids: type: array items: type: string title: The identifiers of the automations to attach to the poll instance connection_id: type: string title: The id of the book connection v1OAuthArgument: type: object properties: id: type: string description: Placeholder id, matching `{id}` in the endpoints. label: type: string description: Human-readable label for the value the caller must provide. required: type: boolean description: |- When true, a connection must supply this argument (or `constant` must be set, or a `capture` must resolve it) or begin is rejected. constant: type: string description: |- Fixed value used when the caller supplies none at connect time (e.g. Azure's `common`). Empty ⇒ the value must come from connect input. capture: $ref: "#/components/schemas/v1ArgumentCapture" description: |- A per-connection template variable (e.g. `tenant`) referenced as `{id}` in the endpoints and supplied when a connection is created. v1ExportAgentResponse: type: object properties: zip_uri: type: string description: |- Presigned download URL for the exported ZIP bundle (valid ~1 hour). The caller can download the bundle directly from this URL. readOnly: true expire_time: type: string format: date-time description: Expiration time of the download URL (1 hour from creation). readOnly: true warnings: type: array items: type: string description: |- Non-fatal warnings produced while building the bundle. A warning does not invalidate the bundle — it records something the destination operator needs to know before or after importing it. Typical cases: an automation referenced a connection that no longer exists in the source workspace (that alias is omitted from the bundle and must be wired up after import), or the agent declared no automations at all, making the bundle agent-only. These warnings are also stored in the bundle itself, so ImportAgent and ValidateAgentImport surface them at the destination. readOnly: true automation_names: type: array items: type: string title: |- Resource names of the automations actually bundled, as selected from the agent's effective tool catalog. Empty for an agent-only bundle. Format: organizations/{organization}/workspaces/{workspace}/automations/{automation} readOnly: true agent_connections: type: array items: $ref: "#/components/schemas/v1AgentConnection" description: |- Book connections the exported agent has attached to itself through its `connection` tool sources. These belong to the agent, not to any bundled automation, and must already exist in the destination workspace for the imported agent to be able to use them. readOnly: true description: Response message for ExportAgent. v2UpdateWorkspaceBookConnectionTriggerInstanceResponse: type: object properties: trigger_instance: $ref: "#/components/schemas/v2TriggerInstance" v1PublishCollectionResponse: type: object properties: collection: $ref: "#/components/schemas/v1Collection" description: Response for PublishCollection. v2RemoveWorkspaceBookConnectionPollInstanceResponse: type: object v2PollInstance: type: object properties: id: type: string title: The identifier of the poll instance name: type: string title: The name of the poll instance book_name: type: string title: The name of the book connection_id: type: string title: The identifier of the book connection poll_id: type: string title: The identifier of the poll configuration: type: object additionalProperties: $ref: "#/components/schemas/bdkv2Value" title: Configuration parameters for the poll workspace_id: type: string title: Workspace ID organization_id: type: string title: Organization ID status: $ref: "#/components/schemas/v2PollInstanceStatus" automation_ids: type: array items: type: string title: Automation IDs associated with this poll instance poll_interval_minutes: type: integer format: int64 title: The poll interval in minutes filter_expression: $ref: "#/components/schemas/bdkv2Expression" v1SecretType: type: object properties: name: type: string description: Full resource name, `secretTypes/{name}`. Server-set on create. id: type: string description: |- Server-generated stable id (NanoID). Used as the FK target on `secrets.secret_type_id`; never sent on create. display_name: type: string description: type: string schema: $ref: "#/components/schemas/v1SecretSchema" kind: $ref: "#/components/schemas/v1SecretTypeKind" create_time: type: string format: date-time update_time: type: string format: date-time labels: type: object additionalProperties: type: string description: Filterable string key/value labels (matched as `labels.`); mutable. description: |- Reusable typed schema for secrets of a given kind. Schemas are stored in the catalog and referenced by name from `Secret.secret_type`. v1IdentifyStepValueSlotsResponse: type: object properties: slots: type: array items: $ref: "#/components/schemas/v1ValueSlot" description: The step's editable value slots. etag: type: string description: |- Opaque version tag of the code these slots were read from (AIP-154). Pass it back to PromoteParamsToCode so a promotion based on a stale read is rejected. description: Response for IdentifyStepValueSlots. v1UpgradeAutomationBookConnectionVersionResponse: type: object properties: automation: $ref: "#/components/schemas/v1Automation" upgraded_connections: type: array items: $ref: "#/components/schemas/v1CredentialInfo" description: |- Connection info for every connection that was newly upgraded on this automation. Each entry reflects the book, version, connection id/alias, and phase of an upgraded connection slot. readOnly: true description: UpgradeAutomationBookConnectionVersionResponse returns the updated automation. FilesServiceGenerateDownloadUrlBody: type: object properties: expire_duration: type: string title: Optional expiration duration format: $ref: "#/components/schemas/v1DownloadFormat" description: If no expiration duration is provided, the default is 1 hour. title: Request to generate presigned download URL v1BatchInsertCollectionRowsResponse: type: object properties: rows: type: array items: $ref: "#/components/schemas/v1CollectionRow" description: The inserted rows in request order, each including its `__row_id__`. readOnly: true description: Response for BatchInsertCollectionRows. v1CollectionSchema: type: object properties: version: type: integer format: int32 description: |- The version number of this schema (monotonically increasing). Server-assigned when the version is created; unset (0) on the CreateCollection input. readOnly: true description: type: string description: Optional human-readable description of this schema version. fields: type: array items: $ref: "#/components/schemas/v1CollectionField" description: |- The fields (columns) of the collection schema, in order. This is the single canonical representation of the schema: each field carries its name, type, description, and per-field metadata (required, unique, default value). Supplied by the caller on the CreateCollection write path and populated by the server on read paths. Field-level edits go through AddCollectionField / UpdateCollectionField / DeleteCollectionField. created_by: type: string description: ID of the user who created this schema version. readOnly: true create_time: type: string format: date-time description: Timestamp when this schema version was created. readOnly: true description: |- A collection's schema at one version. The single representation for schemas on every path: supplied as input on CreateCollection (fields + description; the OUTPUT_ONLY fields are unset and ignored) and returned fully populated on reads (GetCollectionSchema). required: - fields v1QueryGuideStatsResponse: type: object properties: stats: type: array items: $ref: "#/components/schemas/v1GuideStats" title: Statistics for each guide entry next_page_token: type: string description: |- A token to retrieve the next page of results. Pass this value in a subsequent `QueryGuideStats` call to continue listing results. Will be empty when there are no more results. total_size: type: integer format: int32 description: |- The total number of guide entries with statistics across all pages. This count is not affected by pagination parameters. title: Response to a query guide statistics request bdkv2OpaqueValue: type: object properties: content: type: string format: byte title: Content of the opaque value is_a: type: array items: $ref: "#/components/schemas/bdkv2NounPhrase" title: Is a replationships for the opaque v1MissingConnection: type: object properties: phase: type: string description: The phase that requires this connection ("main", "post", or "pre[0]", "pre[1]", etc.). readOnly: true alias: type: string description: The connection alias used in the phase code. readOnly: true book_name: type: string description: The book name that provides this connection type (e.g. "google-sheets"). readOnly: true book_version: type: string description: The book version referenced by the automation. readOnly: true source_connection_display_name: type: string description: The connection display name as referenced by the imported automation. readOnly: true description: A connection referenced by an imported automation that is missing from the workspace. v1ConfigValue: type: object properties: label: type: string description: Human display name shown in the config editor. value: $ref: "#/components/schemas/commonv1Value" description: |- ConfigValue is a single business-tunable configuration value for an automation: the value written when the automation is built, plus the human-readable label shown when tuning it. Config lets an end user adjust automation behavior by editing values, without touching the code. Config entries are carried in a map keyed by the config name (referenced in code as kognitos.config.); the name is not repeated on the message. v1BatchGetRunExecutionTimesResponse: type: object properties: run_execution_times: type: object additionalProperties: $ref: "#/components/schemas/v1RunExecutionTime" description: |- Map from run resource name to its computed execution time. Key: run resource name (same format as BatchGetRunExecutionTimesRequest.names). Value: computed execution time breakdown for that run. description: |- Response message for the BatchGetRunExecutionTimes RPC. Contains the computed execution time for each requested run, keyed by run resource name. All run names specified in BatchGetRunExecutionTimesRequest.names will be present as keys in run_execution_times. AgentImportExportServiceExportAgentBody: type: object properties: agent_version: type: string description: The agent version to export. When empty, the latest version is exported. description: Request message for ExportAgent. v1DeactivateAutomationResponse: type: object properties: automation: $ref: "#/components/schemas/v1Automation" description: DeactivateAutomationResponse returns the deactivated automation. bdkv1Authentication: type: object properties: authentication_id: type: string title: Identifier of the authentication method to be used for testing the connection authentication_credentials: type: array items: $ref: "#/components/schemas/bdkv1CredentialValue" title: Credentials TroubleshootingGuideServiceQueryGuideStatsBody: type: object properties: filter: type: string description: |- The filter to apply when querying guide statistics. Follows Google AIP-160 filtering standard (https://google.aip.dev/160). Supported Fields: - guide_entry: Guide entry ID (not full resource name) - start_time: Filter applications from this time (inclusive, ISO 8601 format) - end_time: Filter applications until this time (exclusive, ISO 8601 format) Supported Operators: - Comparison: =, !=, <, <=, >, >= - Logical: AND, OR, NOT - Grouping: ( ) Timestamp Format: - ISO 8601 with Z suffix: "2025-01-01T00:00:00Z" - ISO 8601 with offset: "2025-01-01T00:00:00+00:00" Filtering Behavior: - The date range filters (start_time, end_time) apply to the filtered_occurrences count - The total_occurrences count always reflects all-time data regardless of time filters Example Filters: - "" - Get statistics for all guide entries under parent - "guide_entry = my-guide-id" - Statistics for a specific guide entry - "guide_entry = id1 OR guide_entry = id2" - Statistics for specific guide entries - "start_time >= \"2025-01-01T00:00:00Z\"" - Applications from Jan 1, 2025 onwards - "start_time >= \"2025-01-01T00:00:00Z\" AND end_time < \"2025-02-01T00:00:00Z\"" - Applications in January 2025 - "guide_entry = my-guide-id AND start_time >= \"2025-01-01T00:00:00Z\"" - Specific guide's applications from Jan 1, 2025 page_size: type: integer format: int32 description: |- The maximum number of guide entries with statistics to return. If unspecified, at most 100 guide entries will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. page_token: type: string description: |- The page token, received from a previous `QueryGuideStats` call. Provide this to retrieve the subsequent page. When paginating, the filter parameter must match the call that provided the page token. title: Request to query guide statistics v1BatchDeleteAssetsResponse: type: object properties: results: type: array items: $ref: "#/components/schemas/v1BatchItemResult" description: Per-item results. Length and order match the request `names` list. readOnly: true description: |- ============================================================= AssetService — batch response messages (ENG-3815) ============================================================= Response for BatchDeleteAssets. Uses BatchItemResult for best-effort per-item status. WorkItemServiceMarkWorkItemPreparationStartedBody: type: object description: MarkWorkItemPreparationStartedRequest identifies the item whose flag is cleared. bdkv2Time: type: object properties: hours: type: integer format: int32 title: Hours of day minutes: type: integer format: int32 title: Minutes of hour of day seconds: type: integer format: int32 title: Seconds of minutes of the time nanos: type: integer format: int32 title: Fractions of seconds in nanoseconds v1ListWorkUnitsResponse: type: object properties: work_units: type: array items: $ref: "#/components/schemas/v1WorkUnit" description: The complete matching units. next_page_token: type: string description: A token to retrieve the next page, or empty if there are no more. total_size: type: integer format: int32 description: The total number of units matching the filter. description: ListWorkUnitsResponse contains a page of workspace units. BadRequestFieldViolation: type: object properties: field: type: string description: |- A path that leads to a field in the request body. The value will be a sequence of dot-separated identifiers that identify a protocol buffer field. Consider the following: message CreateContactRequest { message EmailAddress { enum Type { TYPE_UNSPECIFIED = 0; HOME = 1; WORK = 2; } optional string email = 1; repeated EmailType type = 2; } string full_name = 1; repeated EmailAddress email_addresses = 2; } In this example, in proto `field` could take one of the following values: * `full_name` for a violation in the `full_name` value * `email_addresses[0].email` for a violation in the `email` field of the first `email_addresses` message * `email_addresses[2].type[1]` for a violation in the second `type` value in the third `email_addresses` message. In JSON, the same values are represented as: * `fullName` for a violation in the `fullName` value * `emailAddresses[0].email` for a violation in the `email` field of the first `emailAddresses` message * `emailAddresses[2].type[1]` for a violation in the second `type` value in the third `emailAddresses` message. description: type: string description: A description of why the request element is bad. reason: type: string description: |- The reason of the field-level error. This is a constant value that identifies the proximate cause of the field-level error. It should uniquely identify the type of the FieldViolation within the scope of the google.rpc.ErrorInfo.domain. This should be at most 63 characters and match a regular expression of `[A-Z][A-Z0-9_]+[A-Z0-9]`, which represents UPPER_SNAKE_CASE. localized_message: $ref: "#/components/schemas/rpcLocalizedMessage" description: A message type used to describe a single bad request field. AutomationPhaseServiceUnsetMarkedOutputBody: type: object properties: marked_output: type: string description: The marked output key to remove. description: Request to unset (remove) a single marked output key from an automation. required: - marked_output v2UpdateWorkspaceBookConnectionPollInstanceResponse: type: object properties: poll_instance: $ref: "#/components/schemas/v2PollInstance" WorkItemServiceRevokeWorkUnitInputAcceptanceBody: type: object properties: etag: type: string description: Required current input.response.etag. description: RevokeWorkUnitInputAcceptanceRequest returns the current response to human review. required: - etag v1RunExecutionTime: type: object properties: total_duration: type: string description: |- Total wall-clock duration of the run. Measured from the first recorded state transition to the last. readOnly: true exception_duration: type: string description: |- Total time the run spent waiting for exception resolution. Sum of all intervals spent in the AwaitingGuidance state across all exception cycles during the run. readOnly: true execution_duration: type: string description: |- Net execution time: total_duration minus exception_duration. This is the time the run was actively executing, excluding exception waits. readOnly: true description: |- Computed execution time for a single automation run. Execution time is the net time the run was actively executing, excluding any time spent waiting for exception resolution (AwaitingGuidance state). A run may cycle through the AwaitingGuidance state multiple times; all such intervals are summed and subtracted from the total duration. v1ActivateAutomationResponse: type: object properties: automation: $ref: "#/components/schemas/v1Automation" description: ActivateAutomationResponse returns the activated automation. v1ListWorkItemsResponse: type: object properties: work_items: type: array items: $ref: "#/components/schemas/v1WorkItem" description: |- Matching items, each returned once with counts of all attached units. Unit reads expose individual states and final submissions. next_page_token: type: string description: A token to retrieve the next page, or empty if there are no more. total_size: type: integer format: int32 description: The total number of items matching the filter, so a view can show a count. description: |- ListWorkItemsResponse contains a page of items and the total matching the filter. v1WorkItemUpdate: type: object properties: name: type: string description: WorkItem resource name. revision: type: string format: int64 description: Same ordering token as WorkItem.revision. assignee: type: string description: Assigned user resource name; empty when unassigned. declined_by: type: string description: User who last handed the item back; empty before a decline. decline_reason: type: string description: Reason the item was last handed back. update_time: type: string format: date-time description: Time the item last changed. input_form: $ref: "#/components/schemas/v1FormSpec" input_form_etag: type: string description: Concurrency token for the shared input form. archive_time: type: string format: date-time description: Time of explicit archival; absent when not archived. unit_counts: type: array items: $ref: "#/components/schemas/v1WorkUnitStatusCount" description: Current unit counts grouped by status. preparation_required: type: boolean description: Whether a preparation prompt is pending; does not gate submission. description: |- Complete replacement of an item's mutable projection at one revision. Missing messages, empty strings and false values clear earlier values; this is not a field patch. Immutable identity and question remain on Get/List. An unknown item requires a read before it can be displayed. LibraryServiceAddWorkspaceBookConnectionPollInstanceBody: type: object properties: poll_id: type: string title: The identifier of the poll configuration: type: object additionalProperties: $ref: "#/components/schemas/bdkv2Value" title: Configuration parameters for the poll name: type: string title: The name of the poll instance automation_ids: type: array items: type: string title: Automation IDs to associate with this poll instance poll_interval_minutes: type: integer format: int64 title: The poll interval in minutes filter_expression: $ref: "#/components/schemas/bdkv2Expression" bdkv2Date: type: object properties: year: type: integer format: int32 title: Year of the date month: type: integer format: int32 title: Month of a year day: type: integer format: int32 title: Day of a month ExceptionManagerServiceQueryExceptionInsightsBody: type: object properties: time_window: $ref: "#/components/schemas/v1TimeWindow" description: Request to query exception insights. required: - time_window v1ExportAuditEventsResponse: type: object properties: download_uri: type: string description: A short-lived presigned URI the client can GET to download the export. readOnly: true expire_time: type: string format: date-time description: The time at which download_uri expires. readOnly: true description: Response message for ExportAuditEvents. bdkv2FileValue: type: object properties: remote: type: string inline: $ref: "#/components/schemas/bdkv2File" title: A file value represents a file that can be either inline or remote AutomationServiceActivateAutomationBody: type: object description: ActivateAutomationRequest specifies which automation to activate. v1HarnessInput: type: object properties: name: type: string description: Input parameter name. input_type: type: string description: The input's SPy type. is_file: type: boolean description: True if the input is a file to upload/reference. description: | An input the generated harness expects. AutomationImportExportServiceValidateAutomationImportBody: type: object description: Request message for ValidateAutomationImport. RunServiceReplayRunBody: type: object properties: executable_step: $ref: "#/components/schemas/v1ExecutableStep" stage_version: type: string description: The automation stage version the updated code was saved at. invocation_details: $ref: "#/components/schemas/v1InvocationDetails" description: Request message for ReplayRun method. required: - executable_step - stage_version CollectionRowsServiceImportCollectionBody: type: object properties: source_uri: type: string description: |- The complete Bishop file URL of the previously-uploaded source file. Accepts a canonical bishop:// URI (bishop://{id}--{filename}), a bare resource name (organizations/{org}/.../files/{file}), or a presigned HTTPS download URL. The file must already be uploaded to Bishop. A bishop:// URI is always scope-free (never carries organization/workspace); the bare resource name and HTTPS forms may carry organization/workspace, but any such value is ignored. The file is always resolved within `parent`'s own organization/workspace. format: $ref: "#/components/schemas/v1ImportFormat" options: $ref: "#/components/schemas/v1ImportOptions" stage: $ref: "#/components/schemas/v1CollectionStage" description: Request to import rows into a collection from an uploaded Bishop file. required: - source_uri SecretServiceAdoptSecretBody: type: object properties: name: type: string description: Derived from `secret.display_name` when empty. reference: type: object additionalProperties: type: string description: Opaque reference returned from DiscoverInventory. secret: $ref: "#/components/schemas/v1Secret" backend_id: type: string description: |- Backend the reference lives in. Required: a reference is meaningless without the backend it was discovered from. Pair with the same backend you passed to `DiscoverInventory`. v1PaginateValueContentResponse: type: object properties: chunk: $ref: "#/components/schemas/commonv1Value" next_page_token: type: string description: |- Opaque token for fetching the next page. Empty means there are no additional pages. readOnly: true start_index: type: string format: int64 description: Zero-based start index (or row offset for tables) represented by this chunk. readOnly: true description: Response containing a paginated chunk of an offloaded value. v1StepConfig: type: object properties: automation: type: string title: |- Parent automation. Format: organizations/{organization}/workspaces/{workspace}/automations/{automation} readOnly: true stage: $ref: "#/components/schemas/v1AutomationStage" values: type: object additionalProperties: {} description: |- Candidate/tuned values keyed by ValueSlot.path. google.protobuf.Value to match ValueSlot.value / ParamEdit.value (the promote path); grimoire converts to common.v1.Value when it emits BuildStepHarness.tunable_slots for a run. etag: type: string description: |- Opaque version tag of the draft these values were set against (AIP-154); lets a caller detect the draft changed under an in-flight tuning session. description: |- The candidate/tuned value overlay for one automation stage — the durable store behind uncommitted step testing. Not a resource (a small keyed overlay owned by the automation), addressed by the parent automation + stage. v1DuplicateAutomationResponse: type: object properties: automation: $ref: "#/components/schemas/v1Automation" description: DuplicateAutomationResponse returns the newly created duplicated automation. v1Step: type: object properties: number: type: integer format: int32 description: 1-based sequential step number. call_location: $ref: "#/components/schemas/commonv1Location" entry_function: $ref: "#/components/schemas/v1FunctionNode" audit: $ref: "#/components/schemas/v1Audit" stops: type: array items: $ref: "#/components/schemas/v1Stop" description: |- Deprecated: moved to Audit.stops. Retained for compatibility; do not reuse field number 5. title: type: string description: Step title — the first line of the step function's docstring. overview: type: string description: |- Step overview — the remainder of the step docstring body, excluding the sections parsed into their own fields (Rules, Args, Returns). rules: type: array items: type: string description: "Business rules called out for this step (docstring Rules: section)." args: type: array items: $ref: "#/components/schemas/v1Param" description: |- Step parameters, from the step function's docstring Args: section joined to the signature (name + type + description). returns: type: string description: "Prose description of what the step returns (docstring Returns: section)." phase: type: string description: |- Phase this step belongs to — the title from the nearest preceding phase("...") marker in main(). Empty when the step precedes any marker. The ordered phase list is derived by consumers from steps in order. description: |- Step represents a single top-level step in the analyzed code, corresponding to a user-defined function call in main(). bdkv2BinaryExpression: type: object properties: operator: $ref: "#/components/schemas/bdkv2BinaryOperator" left: $ref: "#/components/schemas/bdkv2Expression" right: $ref: "#/components/schemas/bdkv2Expression" v1GetFolderTreeResponse: type: object properties: roots: type: array items: $ref: "#/components/schemas/v1FolderTreeNode" description: Root-level folder nodes (folders with no parent). readOnly: true description: Response for GetFolderTree — the full folder hierarchy for a workspace. v1ImportCollectionResponse: type: object properties: rows_imported: type: string format: int64 description: Number of rows imported into the collection. readOnly: true column_count: type: integer format: int32 description: Number of columns detected in the source file and written to the collection. readOnly: true schema_version: type: integer format: int32 description: |- The collection's schema version after the import. When the schema was inferred from the source file, this reflects the newly created version. readOnly: true description: Response for ImportCollection. WorkItemServiceSaveWorkUnitAnswerBody: type: object properties: values: type: object additionalProperties: $ref: "#/components/schemas/commonv1Value" description: Complete replacement map; empty clears all values. etag: type: string description: Current answer_draft.etag, including for the first save. description: SaveWorkUnitAnswerRequest replaces partial final-answer values. required: - etag bdkv2EnvironmentInformation: type: object properties: version: type: string runtime_name: type: string title: Runtime name runtime_version: type: string title: Runtime version bci_protocol_version: type: string title: BCI Protocol version api_version: type: string title: BDK API Version path: type: array items: type: string title: Book path under which books will be discovered title: Information about the environment OAuthAppServiceCreateOAuthAppBody: type: object properties: name: type: string description: Derived from `oauth_app.display_name` when empty. oauth_app: $ref: "#/components/schemas/v1OAuthApp" WorkItemServiceAcceptWorkUnitInputBody: type: object properties: etag: type: string description: Required current input.response.etag; accepted values are read server-side. description: AcceptWorkUnitInputRequest accepts exactly the response the caller reviewed. required: - etag v1FolderTreeNode: type: object properties: folder: $ref: "#/components/schemas/v1Folder" children: type: array items: $ref: "#/components/schemas/v1FolderTreeNode" description: Immediate child folders. description: A node in the folder tree returned by GetFolderTree. v1BackendStatus: type: object properties: health: $ref: "#/components/schemas/v1BackendHealth" last_checked: type: string format: date-time message: type: string AgentImportExportServiceImportAgentBody: type: object properties: zip_resource: type: string description: |- Bishop resource name of the ZIP bundle to import. Format: organizations/{organization}/workspaces/{workspace}/files/{name} The caller obtains this by uploading the exported bundle to Bishop in the target workspace; it is not a download URL. description: Request message for ImportAgent. required: - zip_resource v1ListRunAnswersResponse: type: object properties: run_answers: type: array items: $ref: "#/components/schemas/v1RunAnswer" description: The accepted answers in this page. next_page_token: type: string description: Token for the next page, or empty when there are no more answers. description: A page of accepted authoring answers, oldest first. 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. Always empty today: the full set is returned in one response. Present so paging can be introduced without a contract change. description: Response message for ListWorkspacePermissions. TroubleshootingGuideServiceTransitionGuideEntryStateBody: type: object properties: action: $ref: "#/components/schemas/TransitionGuideEntryStateRequestAction" user: type: string description: |- Optional: when omitted, the transition has no attribution (the audit column is left NULL). Internal and test callers that do not carry a user identity can omit it. title: |- The acting user, used by the server to attribute the transition of this guide entry. Format: users/{user} title: Request to transition a guide entry to a new state required: - action v1BatchDownloadFoldersResponse: type: object properties: archive_uri: type: string description: |- Presigned URL for the generated ZIP archive. Valid for `expire_duration` (default 15 minutes). readOnly: true results: type: array items: $ref: "#/components/schemas/v1BatchItemResult" description: Per-item results for folders that could not be fully included in the archive. readOnly: true description: |- Response for BatchDownloadFolders. The server builds a single ZIP preserving the relative folder structure and returns a presigned URL for the archive. ExceptionManagerServiceRetryExceptionsBody: type: object properties: names: type: array items: type: string description: |- The full resource names of the exceptions to retry. Format: organizations/{organization_id}/workspaces/{workspace_id}/exceptions/{exception_id} Duplicate names may be de-duplicated by the server. description: |- Request to retry multiple exceptions in one request. Only PENDING exceptions are retried; RESOLVED and ARCHIVED exceptions are skipped. required: - names bdkv2NounPhrase: type: object properties: modifiers: type: array items: type: string title: Optional adjectives attached to the noun head: type: string title: Noun of the phrase v1ListCollectionRowsResponse: type: object properties: rows: type: array items: $ref: "#/components/schemas/v1CollectionRow" description: |- The list of rows. Each row is a `CollectionRow` wrapping `map` keyed by column name (including `__row_id__`). readOnly: true next_page_token: type: string description: Token to retrieve the next page of results. readOnly: true total_size: type: integer format: int32 description: |- Total rows matching the request filters, across every page. Independent of `page_size` and `page_token`: paging through the collection reports the same value on each response. When no filter is applied this equals the collection's live row count. readOnly: true description: |- ============================================================= CollectionRowsService response messages ============================================================= Response for ListCollectionRows. WorkItemServiceArchiveWorkItemBody: type: object properties: reason: type: string description: Business-safe reason for archival, recorded in the audit event. description: |- ArchiveWorkItemRequest names the item and reason for local dismissal. Rejected with FAILED_PRECONDITION when the kind is not dismissible. required: - reason AutomationPhaseServiceSetMarkedOutputsBody: type: object properties: marked_output: type: string description: The marked output key to add. description: Request to set a single marked output key for an automation. required: - marked_output bdkv1CredentialValue: type: object properties: id: type: string title: Id of the credential value: $ref: "#/components/schemas/bdkv1Value" v1WorkUnit: type: object properties: name: type: string title: |- The stable workspace-scoped resource name of the work unit. Format: organizations/{organization_id}/workspaces/{workspace_id}/workUnits/{work_unit_id} work_item: type: string description: |- Current grouping membership in the same workspace. Rekey may change this reference without changing the unit's name. Empty when the occurrence has no work item. readOnly: true source_ref: type: string description: |- The source's own id for this unit, combined with occurrence_id to identify one request for attention within an organization, workspace and kind across history. The source's shape rather than ours. Decisions also carry occurrence_id so a later request about the same thing cannot consume an earlier answer. Not a label: no kind declares it and no grouping configuration names it. correlation_id: type: string description: |- Source-owned correlation shared by related requests within this organization, workspace and kind. Empty when none was supplied on first admission. Immutable; returned by Get and List and filterable through ListWorkUnits. Independent of work-item grouping, occurrence identity and decision routing. readOnly: true kind: type: string description: |- The registered kind of work, as an opaque dotted id. See WorkItem.kind. readOnly: true labels: type: object additionalProperties: type: string description: |- The facts the source stated about this unit. The subset the workspace groups on became its item's agg_labels, where a key the workspace groups on that this unit does not carry became a null. readOnly: true summary: type: string description: |- One line about this unit in business language, as its source put it. The question, when this is the unit that materialised the item. Immutable for this occurrence, including before acceptance. readOnly: true detail: type: string description: |- Additional source-authored text describing this occurrence. Empty when omitted. Immutable for the occurrence; returned by GetWorkUnit and ListWorkUnits. readOnly: true identifying_details: type: array items: $ref: "#/components/schemas/v1IdentifyingDetail" description: |- Ordered identifying facts, immutable for this occurrence. Entries with a blank label or value are omitted. Clients fall back to summary, then the kind display name when empty; detail is supplementary context, not a heading. readOnly: true evidence: type: object additionalProperties: $ref: "#/components/schemas/commonv1Value" description: |- What a person reads to decide: the records and facts behind this unit, named and typed, so the platform renders it and the source ships no rendering (R6). Immutable for this occurrence. Changed decision context requires withdrawal and a new occurrence. Re-reports never overwrite this evidence. Returned by both GetWorkUnit and ListWorkUnits. readOnly: true status: $ref: "#/components/schemas/v1WorkUnitStatus" delivery: $ref: "#/components/schemas/v1EffectDelivery" settle_time: type: string format: date-time description: "When attention ended for this occurrence: answer, dismissal or withdrawal." readOnly: true create_time: type: string format: date-time description: The time this unit was first seen. readOnly: true update_time: type: string format: date-time description: The time this unit last changed, including by a source's re-report. readOnly: true occurrence_id: type: string description: |- The source's immutable identifier for this particular request for attention. Re-reports reuse it; a new request uses a new one even for the same source_ref. readOnly: true previous_delivery: type: string description: |- Earlier delivery whose rejection or later execution raised this question. Empty for ordinary arrivals. Exposes follow-up provenance to the surface. readOnly: true submission: type: string description: The sole accepted final submission, or empty while no answer is recorded. readOnly: true answer_form: $ref: "#/components/schemas/v1FormSpec" input: $ref: "#/components/schemas/v1InputContext" answer_draft: $ref: "#/components/schemas/v1AnswerDraft" revision: type: string format: int64 description: |- Monotonically increasing version of this resource's mutable state, including resolved input and embedded delivery. Compare only versions of the same resource. Independent of mutation etags. readOnly: true description: |- WorkUnit is one real-world thing needing attention, as its source reported it: a run that failed, a record that was flagged, an automation waiting on a value. The workspace is the resource parent. The name remains stable across rekey; work_item records grouping membership rather than resource parentage. A source reports occurrences without naming an item or asserting grouping. GuideServiceBatchUpdateGuidesBody: type: object properties: requests: type: array items: $ref: "#/components/schemas/v1UpdateGuideRequest" description: |- Between 1 and 100 updates, each with its current etag and explicit mask. A guide may appear only once. Results preserve request order. request_id: type: string description: |- Optional UUIDv4, scoped to the authenticated caller and parent. Within 24 hours, an identical successful request returns its original response without writing again. Reusing the ID with a different payload is INVALID_ARGUMENT. Failed batches do not consume the ID. Without an ID, retries use ordinary etag checks; after expiry, reconcile before retrying. description: BatchUpdateGuidesRequest contains one atomic set of guide edits. required: - requests v1WorkUnitStatusCount: type: object properties: status: $ref: "#/components/schemas/v1WorkUnitStatus" count: type: integer format: int32 description: Number of attached units in this status. Always nonnegative. description: WorkUnitStatusCount counts the attached units in one lifecycle status. v1SecretVersion: type: object properties: secret_id: type: string state: $ref: "#/components/schemas/SecretVersionState" create_time: type: string format: date-time version: type: integer format: int64 bdkv2ListValue: type: object properties: values: type: array items: $ref: "#/components/schemas/bdkv2Value" title: All the values inside the list title: A collection of values v1QueryExceptionInsightsResponse: type: object properties: mttr_seconds: type: number format: double description: |- Mean time to resolution in seconds across all resolved exceptions in the time window. This is the average time from exception creation to resolution. Returns 0 if no exceptions were resolved in the period. readOnly: true description: Response to a query exception insights request. RunServiceAnswerRunBody: type: object properties: invocation_id: type: string description: The current ask invocation, as returned in awaiting_answer. values: type: object additionalProperties: $ref: "#/components/schemas/commonv1Value" description: |- Values keyed by the frozen form's field keys. Missing required fields and values that do not satisfy the frozen form are rejected. description: Request message for AnswerRun. required: - invocation_id - values commonv1Value: type: object properties: null_value: type: string title: Represents the absence of a value (None/null/undefined) bool_value: type: boolean title: Boolean true/false value number: $ref: "#/components/schemas/v1Number" text: type: string title: UTF-8 encoded text string date: $ref: "#/components/schemas/typeDate" timeofday: $ref: "#/components/schemas/typeTimeOfDay" datetime: $ref: "#/components/schemas/typeDateTime" time_zone: $ref: "#/components/schemas/typeTimeZone" duration: type: string title: Signed duration representing a span of time list: $ref: "#/components/schemas/v1List" dictionary: $ref: "#/components/schemas/v1Dictionary" file: $ref: "#/components/schemas/v1FileValue" table: $ref: "#/components/schemas/v1TableValue" set: $ref: "#/components/schemas/v1Set" text_value: $ref: "#/components/schemas/v1TextValue" list_value: $ref: "#/components/schemas/commonv1ListValue" set_value: $ref: "#/components/schemas/v1SetValue" dictionary_value: $ref: "#/components/schemas/v1DictionaryValue" description: |- Represents a runtime value that can be produced by the Jarvis interpreter. This message provides a type-safe way to serialize and transmit values between the Jarvis interpreter and other services via gRPC. It supports all the basic data types that can be represented in the Jarvis language runtime. The oneof structure ensures that exactly one value type is set at a time, providing both type safety and efficient serialization. bdkv2Table: type: object properties: columns: type: array items: $ref: "#/components/schemas/bdkv2Column" description: |- A table is a column-oriented structure. All the values inside each column must be of equal length. v1CollectionRef: type: object properties: collection_id: type: string description: The Bishop collection id that this slug resolves to. stage: $ref: "#/components/schemas/v1CollectionStage" description: CollectionRef references a first-class collection by the id it resolves to. LibraryServiceSetAutomationsForTriggerInstanceBody: type: object properties: automation_ids: type: array items: type: string title: The identifiers of the automations to attach to the trigger instance connection_id: type: string title: The id of the book connection v1ListSecretTypesResponse: type: object properties: secret_types: type: array items: $ref: "#/components/schemas/v1SecretType" next_page_token: type: string v1SortOrder: type: object properties: field: type: string description: Column to sort by, named verbatim. direction: $ref: "#/components/schemas/v1SortDirection" description: |- One column of a row ordering. Column names are carried verbatim, so columns whose names contain spaces or punctuation are sorted on directly. required: - field LibraryServiceUpdateWorkspaceBookConnectionWithRemoteSecretBody: type: object properties: connection_name: type: string title: The connection name credentials_id: type: string description: |- The id of the managed credential backing this connection (resolved at invoke). config_map: type: object additionalProperties: $ref: "#/components/schemas/bdkv2Value" title: Configuration for the connection labels: type: array items: $ref: "#/components/schemas/bdkv2Label" title: Labels associated with the connection authentication_id: type: string description: |- The id of the book authentication method this credential is for. Sets the connection's authenticationId so the runtime knows which method to resolve (the credential values themselves come from the managed store). description: |- Update a credential-backed book connection. Re-points the connection at a managed credential (by id) and/or updates config/labels. Carries no inline authentication values. v1FieldSpec: type: object properties: key: type: string display_name: type: string description: type: string type: $ref: "#/components/schemas/v1FieldType" required: type: boolean default_value: type: string allowed_values: type: array items: type: string description: For FIELD_TYPE_ENUM. SecretServiceCreateSecretBody: type: object properties: name: type: string description: Derived from `secret.display_name` when empty. secret: $ref: "#/components/schemas/v1Secret" backend_id: type: string description: |- Backend that will store this secret. Must exist and serve the requesting scope. If omitted, the server picks the scope's single backend; if the scope has multiple applicable backends, the request is rejected with INVALID_ARGUMENT listing the candidates. v1GenerateAssetDownloadUrlResponse: type: object properties: download_uri: type: string description: Presigned download URL for the asset. Valid for expire_duration (default 1 hour). readOnly: true description: Response for GenerateAssetDownloadUrl. v2RemoveWorkspaceBookConnectionAgentTriggerInstanceResponse: type: object v1MainInfo: type: object properties: location: $ref: "#/components/schemas/commonv1Location" description: MainInfo contains location metadata for the main() function. v1ImportFormat: type: string enum: - IMPORT_FORMAT_UNSPECIFIED - IMPORT_FORMAT_CSV default: IMPORT_FORMAT_UNSPECIFIED description: |- Source file format for an import. Only CSV is supported today. - IMPORT_FORMAT_UNSPECIFIED: Unspecified format; the server treats this as CSV. - IMPORT_FORMAT_CSV: Comma/delimiter separated values. v1FieldType: type: string enum: - FIELD_TYPE_UNSPECIFIED - FIELD_TYPE_STRING - FIELD_TYPE_INTEGER - FIELD_TYPE_BOOL - FIELD_TYPE_ENUM - FIELD_TYPE_SECRET_REFERENCE default: FIELD_TYPE_UNSPECIFIED description: |2- - FIELD_TYPE_SECRET_REFERENCE: Sensitive: UI masks input. On write, the server stores the value in a core/v1.Secret and replaces it with a reference object. Never echoed on read. v1AutomationCollectionUsage: type: object properties: automation_id: type: string description: |- The automation ID that uses the collection. This is the automation ID portion only (e.g., the {automation} part of the resource name). display_name: type: string description: Display name of the automation (denormalized for UI convenience). usage_type: $ref: "#/components/schemas/v1CollectionUsageType" description: |- AutomationCollectionUsage represents an automation that uses a specific collection, along with how it uses it (read or write). v2AddWorkspaceBookConnectionPollInstanceResponse: type: object properties: poll_instance: $ref: "#/components/schemas/v2PollInstance" v1AuditActor: type: object properties: user_id: type: string description: The unique identifier of the acting user, if a user initiated the action. display_name: type: string description: Human-readable display name of the actor at the time of the event. email: type: string description: Email of the acting user at the time of the event. actor_type: $ref: "#/components/schemas/v1AuditActorType" pat_id: type: string description: The personal access token id, if the action was performed via a PAT. description: AuditActor identifies who performed an audited action. LibraryServiceCopyAndUpgradeWorkspaceBookConnectionBody: type: object properties: new_book_version: type: string description: |- The new version to upgrade book to on the copied connection. Must differ from book_version; same-version copies are not supported. 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. v2UpdateWorkspaceBookConnectionAgentTriggerInstanceResponse: type: object properties: agent_trigger_instance: $ref: "#/components/schemas/v2AgentTriggerInstance" v1ReplaceFileContentResponse: type: object properties: metadata: $ref: "#/components/schemas/v1FileMetadata" title: |- Response after replacing a file's content For HTTP/REST: Returns JSON with metadata HTTP Status: 200 OK v2AgentTriggerInstance: type: object properties: id: type: string title: The identifier of the agent trigger instance name: type: string title: The name of the agent trigger instance reference: type: string title: The reference of the agent trigger instance book_name: type: string title: The name of the book connection_id: type: string title: The identifier of the book connection trigger_id: type: string title: The name of the trigger configuration: type: object additionalProperties: $ref: "#/components/schemas/bdkv2Value" title: Configuration parameters for the trigger endpoint: type: string title: The endpoint of the agent trigger instance agent_ids: type: array items: type: string description: |- Identifiers of the rain agents to invoke when the trigger fires. Each agent gets its own thread and message; the prompt is sent to all. prompt: type: string title: Literal prompt sent to the rain agent as the user message workspace_id: type: string title: Workspace ID organization_id: type: string title: Organization ID filter_expression: $ref: "#/components/schemas/bdkv2Expression" status: $ref: "#/components/schemas/v2TriggerInstanceStatus" v1ImportOptions: type: object properties: first_row: $ref: "#/components/schemas/v1ImportFirstRowMode" delimiter: type: string description: Field delimiter for CSV files. A single character; empty defaults to ",". description: Optional parsing options for an import. v2RetrieveWorkspacePollInstancesResponse: type: object properties: poll_instances: type: array items: $ref: "#/components/schemas/v2PollInstance" title: The poll instances AssetFolderServiceBatchDownloadFoldersBody: type: object properties: names: type: array items: type: string title: |- Resource names of the folders to include. Max 20 per request. Format: organizations/{organization}/workspaces/{workspace}/folders/{folder} expire_duration: type: string description: "Optional URL expiry duration for the archive download URL. Default: 15 minutes." description: |- Request to download a ZIP archive of multiple folders. The server recursively collects all assets within each folder (including descendants), builds a ZIP preserving the relative folder structure, and returns a single presigned URL. Folders are processed independently; per-item errors are recorded in the response. required: - names CollectionRowsServiceListCollectionRowsBody: type: object properties: page_size: type: integer format: int32 description: "Maximum number of rows to return. Default: 50. Max: 10000." page_token: type: string description: |- Continuation token from a previous call, or an absolute row offset (e.g. "50") for offset-based paging. Empty starts at the first row. filter: type: string description: |- AIP-160 filter expression to match rows. Deprecated: use `structured_filter` instead. order_by: type: string description: |- Comma-separated list of column names to sort by, with optional " asc" / " desc" suffix. Deprecated: use `structured_order_by` instead. stage: $ref: "#/components/schemas/v1CollectionStage" structured_filter: $ref: "#/components/schemas/v1RowFilter" structured_order_by: type: array items: $ref: "#/components/schemas/v1SortOrder" description: "Ordering applied to matching rows. Default: `__row_id__` ascending." description: |- ============================================================= CollectionRowsService request messages ============================================================= Request to list rows from a collection. Rows in the response are typed `map` wrapped in `CollectionRow` (for `repeated` compatibility). v1CollectionStage: type: string enum: - COLLECTION_STAGE_UNSPECIFIED - COLLECTION_STAGE_DRAFT - COLLECTION_STAGE_PUBLISHED default: COLLECTION_STAGE_UNSPECIFIED description: |- CollectionStage identifies which stage of a collection a request targets. - COLLECTION_STAGE_UNSPECIFIED: Stage not specified. - COLLECTION_STAGE_DRAFT: The draft stage. - COLLECTION_STAGE_PUBLISHED: The published stage. v1CodeOutput: type: object properties: name: type: string description: Output name (the key passed to set_output). type: $ref: "#/components/schemas/v1ValueType" description: type: string description: "Description from the main() docstring Outputs: section (join by name)." description: CodeOutput represents a single output derived from set_output() calls. v1InspectStepConfigResponse: type: object properties: config: $ref: "#/components/schemas/v1StepConfig" description: Response for InspectStepConfig. JarvisServiceRunCodeBody: type: object properties: start_execution: type: object properties: run_id: type: string title: "Optional: Run identifier" code: type: string title: The SPy code to execute inputs: type: object additionalProperties: $ref: "#/components/schemas/commonv1Value" title: Input variables available to the code during execution connections: type: object additionalProperties: $ref: "#/components/schemas/v1BookConnection" title: |- External book connections required by the code The key is the name of the connection used in the SPy code The value contains the connection details record_execution_id: type: string description: |- Optional execution_id of the recorded execution to be used for replaying BDK procedure calls (that have side-effects). DEPRECATED: Use record_mode.replay_record.execution_id instead. phase_execution_id: type: string description: |- Optional execution_id of a previous execution to inherit memory state from. When specified, the execution will start fresh but with memory variables loaded from the checkpoint of the specified execution_id. automation_id: type: string title: Optional id of the automation which the execution is part of automation_phase_id: type: string title: Optional id of the automation phase which the execution is part of no_recording: $ref: "#/components/schemas/v1NoRecording" record_only: $ref: "#/components/schemas/v1RecordOnly" replay_record: $ref: "#/components/schemas/v1ReplayRecord" replay_only: $ref: "#/components/schemas/v1ReplayOnly" stage: $ref: "#/components/schemas/v1AutomationStage" extra_metadata: type: object additionalProperties: $ref: "#/components/schemas/commonv1Value" description: |- Optional extra metadata to be stored with the execution This will be used to pass the additional information that downstream services might require but there is no need to Jarvis to know about it. entry_point: type: string description: |- The name of the SPy function to invoke as the entry point. When set, Jarvis executes this function instead of the default "main", mapping the provided inputs to the function's parameters. Defaults to "main" when not specified. collections: type: object additionalProperties: $ref: "#/components/schemas/v1CollectionRef" description: |- First-class collections referenced by the SPy code, delivered as a slug -> CollectionRef map. The key is the collection slug used in `kognitos.collection..(...)`; the value carries the Bishop collection id that Jarvis resolves at call time. Jarvis never mints slugs or ids -- it only resolves them. config: type: object additionalProperties: $ref: "#/components/schemas/commonv1Value" description: |- First-class config values read by the SPy code via kognitos.config.. The key is the config name; the value carries the resolved read-only value. Config is read-only during execution -- these values are resolved at start and never written back. title: The start execution command title: Request body to run the Spy Code required: - start_execution SecretServiceAddSecretVersionBody: type: object properties: payload: $ref: "#/components/schemas/v1SecretPayload" oauth_payload: $ref: "#/components/schemas/v1OAuthPayload" AssetFolderServiceBatchDuplicateFoldersBody: type: object properties: names: type: array items: type: string title: |- Resource names of the folders to duplicate. Max 100 per request. Format: organizations/{organization}/workspaces/{workspace}/folders/{folder} destination_parent_folder_name: type: string title: |- Optional destination parent for all copies. Empty (default) places each copy under the same parent as its original. Format: organizations/{organization}/workspaces/{workspace}/folders/{folder} description: |- Request to deep-duplicate multiple folders in a single best-effort call. Each folder (and its entire subtree + assets) is duplicated independently. required: - names RunServiceArchiveRunsBody: type: object properties: names: type: array items: type: string title: |- The unique identifiers of the runs to archive. Format: organizations/{organization}/workspaces/{workspace}/automations/{automation}/runs/{run} description: |- Request message for ArchiveRuns method. Specifies which runs to archive by their unique identifiers. required: - names v1CreateRunAssistantResponse: type: object properties: rain_thread_id: type: string description: The Rain thread id for this run assistant session. readOnly: true description: Response containing the created run assistant's Rain thread id. v1Submission: type: object properties: name: type: string description: Full unit-scoped resource name. The identifier is server-generated. answer: $ref: "#/components/schemas/v1Answer" submitter: type: string title: |- Server-derived authenticated actor. An agent acting on a user's behalf is attributed to that user; this field does not establish human approval. Format: users/{user_id} readOnly: true descriptor_version: type: string format: int64 description: Version of the kind descriptor used to create the delivery obligation. readOnly: true create_time: type: string format: date-time description: Time the answer and delivery obligation became durable. readOnly: true description: |- Submission is one immutable final answer to one work-unit occurrence. A unit accepts at most one submission. Its decision delivery is recorded in the same transaction. Source rejection or delivery failure never replaces it; a different final answer requires a new source occurrence. required: - answer v1AuditActorType: type: string enum: - AUDIT_ACTOR_TYPE_UNSPECIFIED - AUDIT_ACTOR_TYPE_USER - AUDIT_ACTOR_TYPE_SERVICE - AUDIT_ACTOR_TYPE_SYSTEM - AUDIT_ACTOR_TYPE_SUPPORT default: AUDIT_ACTOR_TYPE_UNSPECIFIED description: |- AuditActorType classifies the kind of actor that performed an action. Mirrors common.v1.AuditActorType (the Kafka payload enum). - AUDIT_ACTOR_TYPE_UNSPECIFIED: Actor type is not specified. - AUDIT_ACTOR_TYPE_USER: A human user. - AUDIT_ACTOR_TYPE_SERVICE: Another Kognitos service acting on its own behalf. - AUDIT_ACTOR_TYPE_SYSTEM: The platform itself (automated/system-initiated action). - AUDIT_ACTOR_TYPE_SUPPORT: A Kognitos support/staff user acting on a customer's behalf. v1GetHermesExceptionContextResponse: type: object properties: content: type: string description: |- The `` block, ready to send to the agent verbatim. A part with nothing recorded behind it is left out rather than sent empty: the agent's instructions branch on whether a source window is present, and an empty tag claiming to be the source is worse than no tag. So a thin payload is a successful response, not an error. readOnly: true description: The rendered `` payload. AssetServiceGenerateAssetDownloadUrlBody: type: object properties: expire_duration: type: string description: "Optional URL expiry duration. Default: 1 hour." description: |- Request to generate a presigned download URL for an asset. Delegates to Bishop FilesService.GenerateDownloadUrl internally. v1BatchUpdateGuidesResponse: type: object properties: guides: type: array items: $ref: "#/components/schemas/v1Guide" description: Updated guides, including their new etags. description: BatchUpdateGuidesResponse contains the committed guides in request order. v1CollectionRow: type: object properties: fields: type: object additionalProperties: $ref: "#/components/schemas/commonv1Value" description: Column name → value. Includes `__row_id__` on read paths. description: |- A single row in a collection, as a typed key-value map. Wraps `map` so it can be used in `repeated` fields (proto3 forbids `repeated map<...>` directly). Keys are column names (including the internal `__row_id__` column); values carry their full Jarvis runtime type via `common.v1.Value`. required: - fields LibraryServiceUpdateWorkspaceBookConnectionAgentTriggerInstanceBody: type: object properties: name: type: string title: The name of the agent trigger instance (required for PUT semantics) configuration: type: object additionalProperties: $ref: "#/components/schemas/bdkv2Value" description: |- Configuration parameters for the trigger (required for PUT semantics). Empty map clears the configuration. filter_expression: $ref: "#/components/schemas/bdkv2Expression" agent_ids: type: array items: type: string description: |- Identifiers of the rain agents to invoke when the trigger fires (required for PUT semantics). Each agent gets its own thread and message; the prompt is sent to all. prompt: type: string title: Literal prompt sent to the rain agent as the user message (required for PUT semantics) commonv1ListValue: type: object properties: remote: type: string title: Reference to remote list data via URL or file path inline: $ref: "#/components/schemas/v1List" description: |- Represents a list value that can be either stored inline or referenced remotely. This message provides flexibility for handling large lists: - Small lists can be embedded directly using the inline option - Large lists can be referenced by URL using the remote option bdkv2SensitiveValue: type: object properties: value: $ref: "#/components/schemas/bdkv2Value" title: A sensitive value is any value marked as sensitive (to prevent exposure) v2SpySignatureDescriptor: type: object properties: function_name: type: string title: Name of the function arguments: type: array items: $ref: "#/components/schemas/v2SpyArgumentDescriptor" title: Arguments of the function, in call order return_type: $ref: "#/components/schemas/bdkv2ConceptType" description: type: string title: Description of the procedure title: The SPy signature of a book procedure v1OAuthGrantType: type: string enum: - OAUTH_GRANT_TYPE_UNSPECIFIED - OAUTH_GRANT_TYPE_AUTHORIZATION_CODE - OAUTH_GRANT_TYPE_CLIENT_CREDENTIALS default: OAUTH_GRANT_TYPE_UNSPECIFIED description: |- OAuth grant type. UNSPECIFIED is treated as AUTHORIZATION_CODE (back-compat with apps registered before this field existed). AutomationPhaseServiceActivateTriggerBody: type: object properties: stage: $ref: "#/components/schemas/v1AutomationStage" description: Request to activate a trigger for an automation. required: - stage v1GuideApplication: type: object properties: guide_entry: type: string title: |- The guide entry resource name. Format: organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/guideEntries/{guide_entry_id} readOnly: true exception: type: string title: |- The exception resource name. Format: organizations/{organization_id}/workspaces/{workspace_id}/exceptions/{exception_id} readOnly: true run: type: string title: |- The run resource name. Format: organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id} readOnly: true automation: type: string title: |- The automation resource name. Format: organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id} readOnly: true applied_time: type: string format: date-time title: When the guide was applied readOnly: true title: A record of a guide entry being applied to resolve an exception v1CurrentUserOrganizationRolesResponse: type: object properties: roles: type: array items: $ref: "#/components/schemas/v1Role" description: List of roles the current user has in the organization. description: Response message for CurrentUserOrganizationRoles. v1Backend: type: object properties: name: type: string description: |- The `{id}` segment is server-generated (e.g. `aws-7az92kdr`); see [CreateBackendRequest]. The full resource name is what callers pass back to `GetBackend` / `DeleteBackend`. The trailing id segment is what callers use as `backend` on `CreateSecret`, `AdoptSecret`, and `DiscoverInventory`. title: |- Resource name. One of: backends/{id} (platform default) organizations/{org}/backends/{id} (org-scoped) organizations/{org}/workspaces/{ws}/backends/{id} (workspace-scoped) type_id: type: string description: |- Stable identifier matching a BackendTypeInfo.type_id returned by ListBackendTypes. e.g. "aws-secrets-manager" for BYO, "kognitos-managed" for the platform default (opaque — implementation hidden from callers). config: type: object description: |- Backend-specific configuration. Schema lives in the catalog (`BackendTypeInfo.config_fields`); server validates at write time. auth: $ref: "#/components/schemas/v1AuthConfig" status: $ref: "#/components/schemas/v1BackendStatus" create_time: type: string format: date-time etag: type: string kognitos_managed: type: boolean description: |- True when this backend is the Kognitos-managed platform default — its implementation, config, and credentials are entirely opaque to the customer and only Kognitos can change it. False for customer- owned backends (BYO), which the customer creates, configures, and can update or delete. display_name: type: string description: |- Human-readable label, customer-chosen at create time. Mutable via UpdateBackend without changing the resource name. Required on `CreateBackend` (server rejects empty); on read-back, falls back to the trailing-segment id for backends predating this field. v1GuideStats: type: object properties: guide_entry: type: string title: |- The guide entry resource name. Format: organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/guideEntries/{guide_entry_id} readOnly: true total_occurrences: type: integer format: int32 title: Total number of times this guide has been applied to resolve exceptions readOnly: true filtered_occurrences: type: integer format: int32 description: |- Number of times this guide has been applied within the requested date range. If no date range was specified in the request, equals total_occurrences. readOnly: true successful_occurrences: type: integer format: int32 description: |- Number of applications that durably resolved the exception, i.e. the same failure (matching error message at a nearby code location) did not recur later in the same run. Always <= total_occurrences. readOnly: true success_rate: type: number format: float description: |- The durable success rate of this guide: successful_occurrences / total_occurrences, in the range [0, 1]. Zero when total_occurrences is 0. "Success" means the same failure did not recur in the run after the guide was applied; it is a durability proxy, not a guarantee the business outcome was correct. readOnly: true title: Usage statistics for a guide entry AutomationPhaseServiceDeactivateTriggerBody: type: object properties: stage: $ref: "#/components/schemas/v1AutomationStage" description: Request to deactivate a trigger for an automation. required: - stage v1RunCodeResponse: type: object properties: execution_status: $ref: "#/components/schemas/v1ExecutionStatus" description: RunCodeResponse contains the execution status. required: - execution_status v1BatchDuplicateAssetsResponse: type: object properties: results: type: array items: $ref: "#/components/schemas/v1BatchItemResult" description: |- Per-item results. Length and order match the request `names` list. On success, `BatchItemResult.name` is the resource name of the new copy. readOnly: true description: Response for BatchDuplicateAssets. AssetFolderServiceMoveFolderBody: type: object properties: destination_parent_folder_name: type: string title: |- New parent folder resource name. Empty string means move to the workspace root (no parent). Format: organizations/{organization}/workspaces/{workspace}/folders/{folder} description: |- ============================================================= AssetFolderService — single-item custom-method request messages (ENG-3815) ============================================================= Request to move a folder to a new parent (reparent). Returns FAILED_PRECONDITION if the move would create a cycle. AssetFolderServiceBatchMoveFoldersBody: type: object properties: names: type: array items: type: string title: |- Resource names of the folders to move. Max 100 per request. Format: organizations/{organization}/workspaces/{workspace}/folders/{folder} destination_parent_folder_name: type: string title: |- New parent folder resource name for all folders in `names`. Empty string means move to the workspace root. Format: organizations/{organization}/workspaces/{workspace}/folders/{folder} description: |- Request to move multiple folders to a destination parent in a single best-effort call. Each folder is moved independently; failures (including cycle detection) are recorded per-item. required: - names v1RowFilter: type: object properties: logical: $ref: "#/components/schemas/v1LogicalGroup" negation: $ref: "#/components/schemas/v1RowFilter" comparison: $ref: "#/components/schemas/v1Comparison" fuzzy_match: $ref: "#/components/schemas/v1FuzzyMatch" description: |- Structured predicate over the rows of a file. Field names are carried verbatim, so columns whose names contain spaces or punctuation are addressed directly, without quoting or escaping. This is the typed alternative to the AIP-160 `filter` string on the row requests. FilesServiceGenerateUploadUrlBody: type: object properties: expire_duration: type: string title: Optional expiration duration description: If no expiration duration is provided, the default is 1 hour. title: Request to generate presigned upload URL LibraryServiceRetrieveWorkspaceBookConnectionsByIdsBody: type: object properties: connection_ids: type: array items: type: string description: The list of connection ids to retrieve. description: |- Retrieve multiple workspace book connections by their connection IDs. This is intended as a batch-get API for clients (e.g. Grimoire) that already know the specific connection_id values they need, and want to avoid the LIST-based RetrieveAllWorkspaceBookConnections hot path. bdkv1Value: type: object properties: null_value: type: string conceptual_value: $ref: "#/components/schemas/bdkv1NounPhrase" text_value: type: string number_value: type: number format: double boolean_value: type: boolean datetime_value: type: string format: date-time date_value: $ref: "#/components/schemas/bdkv1Date" time_value: $ref: "#/components/schemas/bdkv1Time" file_value: $ref: "#/components/schemas/bdkv1FileValue" dictionary_value: $ref: "#/components/schemas/bdkv1DictionaryValue" list_value: $ref: "#/components/schemas/bdkv1ListValue" opaque_value: $ref: "#/components/schemas/bdkv1OpaqueValue" table_value: $ref: "#/components/schemas/bdkv1TableValue" sensitive_value: $ref: "#/components/schemas/bdkv1SensitiveValue" title: A union of all possible values v1AnswerDraft: type: object properties: values: type: object additionalProperties: $ref: "#/components/schemas/commonv1Value" description: |- Supplied fields must validate; required top-level fields may be omitted. Supplied structured values must be complete. Unknown keys fail. readOnly: true etag: type: string description: |- Concurrency token, present before the first save. Changes on saves. Clearing values never reuses a token. readOnly: true updated_by: type: string description: Authenticated actor who last saved values; empty before the first save. readOnly: true update_time: type: string format: date-time description: Time of the latest save. readOnly: true description: |- Partial final-answer values for one immutable source answer contract. Saving is optional and never accepts input or settles the unit. v1AuthConfig: type: object properties: method: type: string description: |- Auth method id matching an AuthMethodSpec.id in the type's catalog entry. e.g. "default", "static_keys", "assume_role". fields: type: object description: |- Method-specific field values. SECRET_REFERENCE-typed fields submitted here are written by the server to a core/v1.Secret in the `gringotts` namespace; the CRD stores only the reference. On read-back they are suppressed entirely. v1ListAuditEventsResponse: type: object properties: audit_events: type: array items: $ref: "#/components/schemas/v1AuditEvent" description: The page of audit events, ordered per the request (newest first by default). next_page_token: type: string description: A token to retrieve the next page, or empty if there are no more results. description: Response message for ListAuditEvents. v1TextValue: type: object properties: remote: type: string title: Reference to remote text content via URL or file path inline: type: string title: Text content embedded directly in the message description: |- Represents a text value that can be either stored inline or referenced remotely. This message provides flexibility for handling text strings in the Jarvis interpreter: - Small strings can be embedded directly using the inline option - Large strings can be referenced by URL using the remote option - The choice depends on string size, network constraints, and access patterns bdkv1Time: type: object properties: hours: type: integer format: int32 title: Hours of day minutes: type: integer format: int32 title: Minutes of hour of day seconds: type: integer format: int32 title: Seconds of minutes of the time nanos: type: integer format: int32 title: Fractions of seconds in nanoseconds v1UnarchiveExceptionsResponse: type: object properties: unarchived_count: type: integer format: int32 description: Number of exceptions transitioned from ARCHIVED to PENDING state. description: Response for unarchiving exceptions. v1WorkUnitUpdate: type: object properties: name: type: string description: Stable WorkUnit resource name, including after rekey. revision: type: string format: int64 description: Same ordering token as WorkUnit.revision. work_item: type: string description: Current parent WorkItem resource name. status: $ref: "#/components/schemas/v1WorkUnitStatus" delivery: $ref: "#/components/schemas/v1EffectDelivery" settle_time: type: string format: date-time description: Time the unit settled; absent while unresolved. update_time: type: string format: date-time description: Time the unit last changed. submission: type: string description: Accepted final Submission resource name; empty before submission. input: $ref: "#/components/schemas/v1InputContext" answer_draft: $ref: "#/components/schemas/v1AnswerDraft" previous_work_item: type: string description: |- Previous membership when this update moves the unit. Empty otherwise. A departure removes membership, never the resource itself. labels: type: object additionalProperties: type: string description: Current source labels, refreshed by live re-reports. Empty clears earlier labels. description: |- Complete replacement of a unit's mutable projection at one revision. Missing messages and empty strings clear earlier values. Immutable evidence, identifying details and source answer schema remain on Get/List. Unknown units require a read. Changes of item membership reach both subscriptions. v1ListOAuthAppsResponse: type: object properties: oauth_apps: type: array items: $ref: "#/components/schemas/v1OAuthApp" next_page_token: type: string v1SecretState: type: string enum: - SECRET_STATE_UNSPECIFIED - SECRET_STATE_ACTIVE - SECRET_STATE_PENDING_AUTHORIZATION - SECRET_STATE_DEGRADED default: SECRET_STATE_UNSPECIFIED description: |- Lifecycle state of a Secret. - SECRET_STATE_ACTIVE: Usable — a current version is available. - SECRET_STATE_PENDING_AUTHORIZATION: OAuth consent not yet completed (no version written). - SECRET_STATE_DEGRADED: Backing store compromised (see `state_reason` for the precise cause). LibraryServiceAddWorkspaceBookConnectionWithRemoteSecretBody: type: object properties: connection_name: type: string title: The connection name credentials_id: type: string description: |- The id of the managed credential backing this connection (resolved at invoke). Required. config_map: type: object additionalProperties: $ref: "#/components/schemas/bdkv2Value" title: Configuration for the connection labels: type: array items: $ref: "#/components/schemas/bdkv2Label" title: Labels associated with the connection associated_remote_connection_id: type: string title: The id of the associated remote connection authentication_id: type: string description: |- The id of the book authentication method this credential is for. Sets the connection's authenticationId so the runtime knows which method to resolve (the credential values themselves come from the managed store). description: |- Add a book connection whose credential is a managed secret referenced by id. The connection carries no inline authentication values — the runtime resolves the credential from the managed store at invoke. v1ListBackendsResponse: type: object properties: backends: type: array items: $ref: "#/components/schemas/v1Backend" next_page_token: type: string v1ValidateSecretSchemaRequest: type: object properties: schema: $ref: "#/components/schemas/v1SecretSchema" payload: $ref: "#/components/schemas/v1SecretPayload" AutomationServicePromoteParamsToCodeBody: type: object properties: params: type: array items: $ref: "#/components/schemas/v1ParamEdit" description: Edits to apply to the draft source (paths are self-addressing per value slot). etag: type: string description: |- Optimistic-concurrency tag (AIP-154) from the IdentifyStepValueSlots / BuildStepHarness response the edits were derived from. When set, the promote is rejected with ABORTED if the draft has since changed; when empty, the edits are applied to the current draft (last-writer-wins). description: Request for PromoteParamsToCode. Always targets the DRAFT stage. required: - params v1EffectDelivery: type: object properties: name: type: string description: Resource name; the final segment is the dispatch_id given to the source. work_unit: type: string description: The unit whose decision this delivers. readOnly: true submission: type: string description: The final submission this delivers; always present. readOnly: true attempt_count: type: integer format: int32 description: Count of publish attempts across automatic and operator retry cycles. readOnly: true publish_time: type: string format: date-time description: First successful broker acknowledgement. Absent before publication. readOnly: true result_time: type: string format: date-time description: Time Workbench durably received a terminal source result. readOnly: true outcome: $ref: "#/components/schemas/v1DecisionOutcome" rejection_reason: type: string description: Source rejection reason, present only for REJECTED. readOnly: true confirmation_deadline: type: string format: date-time description: |- Fixed at first successful publication. Passing this time without a result means confirmation overdue, never that delivery or application failed. readOnly: true attention_required_time: type: string format: date-time description: |- When automatic retries stopped pending operator attention. A late result remains admissible. This is not a terminal source result. readOnly: true last_error: type: string description: |- Business-safe operational diagnostic, distinct from a source rejection. No traceback, internal identifier or resource name; richer detail is logged. readOnly: true description: |- EffectDelivery is the durable obligation to deliver one decision to one unit. A source result is independent of publication and of unit settlement. v1ImportAgentResponse: type: object properties: agent: type: string title: |- The resource name of the newly created agent. Format: organizations/{organization}/workspaces/{workspace}/agents/{agent} readOnly: true automation_names: type: array items: type: string title: |- Resource names of the newly created draft automations bundled with the agent. Format: organizations/{organization}/workspaces/{workspace}/automations/{automation} readOnly: true warnings: type: array items: type: string description: |- Non-fatal warnings produced while applying the agent (e.g. from the agent service), such as unchanged sub-agents or advisory notices. readOnly: true agent_connections: type: array items: $ref: "#/components/schemas/v1AgentConnection" description: |- Book connections the newly imported agent expects on itself, carried over from the exported agent's `connection` tool sources. Import does not create these connections; wire them up in the target workspace right afterwards. readOnly: true description: Response message for ImportAgent. v1GuideAssetSource: type: object properties: name: type: string description: Full workspace-scoped asset resource name. description: GuideAssetSource identifies a Library asset whose current contents are read. required: - name rpcLocalizedMessage: type: object properties: locale: type: string title: |- The locale used following the specification defined at https://www.rfc-editor.org/rfc/bcp/bcp47.txt. Examples are: "en-US", "fr-CH", "es-MX" message: type: string description: The localized error message in the above locale. description: |- Provides a localized error message that is safe to return to the user which can be attached to an RPC error. v1CollectionUsage: type: object properties: collection: type: string description: The collection traced, as given in the request. automations: type: array items: $ref: "#/components/schemas/v1AutomationCollectionUsage" description: |- Automations that use this collection, with their usage type; the same list TraceCollectionUsage returns. Empty when no automation uses it. description: CollectionUsage lists the automations that use one collection. v1LogicalGroup: type: object properties: operator: $ref: "#/components/schemas/v1LogicalOperator" operands: type: array items: $ref: "#/components/schemas/v1RowFilter" description: Sub-filters combined by `operator`. description: A set of sub-filters joined by a single logical operator. required: - operator - operands v1SetValue: type: object properties: remote: type: string title: Reference to remote set data via URL or file path inline: $ref: "#/components/schemas/v1Set" description: |- Represents a set value that can be either stored inline or referenced remotely. This message provides flexibility for handling large sets: - Small sets can be embedded directly using the inline option - Large sets can be referenced by URL using the remote option bdkv1TableValue: type: object properties: remote: type: string inline: $ref: "#/components/schemas/bdkv1Table" title: |- A table that is represented remote as an URL to a file that is Feather-formatted or inline via the Table message v1AutomationInputDiff: type: object properties: added: type: array items: $ref: "#/components/schemas/v1AutomationInputSpec" description: Input specs present in this revision but not in the previous revision. readOnly: true removed: type: array items: $ref: "#/components/schemas/v1AutomationInputSpec" description: Input specs present in the previous revision but not in this revision. readOnly: true modified: type: array items: $ref: "#/components/schemas/v1AutomationInputSpec" description: |- Input specs present in both revisions (matched by name) whose type differs. Each entry is the spec as of this (current) revision. readOnly: true description: |- AutomationInputDiff describes how an automation's input specifications changed between two revisions. Only input specs (name and type) are compared; default input values are not, since changing a default value does not create a new revision. v1FormField: type: object properties: key: type: string description: Stable record key. Unique within its field set; nonempty. label: type: string description: Business-facing wording, independent of the programmatic key; nonempty. help_text: type: string description: Optional guidance displayed with the question. value_type: $ref: "#/components/schemas/v1ValueType" initial_value: $ref: "#/components/schemas/commonv1Value" text: $ref: "#/components/schemas/v1TextConstraints" number: $ref: "#/components/schemas/v1NumberConstraints" input_spec: $ref: "#/components/schemas/v1InputSpec" description: One named question, its answer type and its input behavior. required: - key - label - value_type bdkv1Date: type: object properties: year: type: integer format: int32 title: Year of the date month: type: integer format: int32 title: Month of a year day: type: integer format: int32 title: Day of a month v1User: type: object properties: name: type: string description: |- The unique resource name of the user. Format: `users/{user}` 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. display_name: type: string description: The user's display name. email: type: string description: The user's email address. This is required and unique. provider_id: type: string description: |- The identifier provided by the authentication provider (e.g., Auth0 user ID). This field is used to link the user account with external authentication systems. create_time: type: string format: date-time description: |- The timestamp when the user was created. This is an output-only field, populated by the server. readOnly: true update_time: type: string format: date-time description: |- The timestamp when the user was last updated. This is an output-only field, populated by the server. readOnly: true onboarding_state: $ref: "#/components/schemas/v1OnboardingState" last_org: type: string title: |- The resource name of the last organization viewed by the user. Format: `organizations/{organization}` last_workspace: type: string title: |- The resource name of the last workspace viewed by the user. Format: `organizations/{organization}/workspaces/{workspace}` avatar_data_uri: type: string description: |- The user's profile avatar as a data URI following RFC 2397. (MAN-3387) Format: data:[][;encoding], Example: data:image/png;encoding, Server-side max payload size: 1MB. state: $ref: "#/components/schemas/v1UserState" last_active_time: type: string format: date-time description: |- The most recent timestamp the user was seen (token validation / CurrentUser call). (MAN-3390) Output-only; written debounced on auth events. readOnly: true description: A user resource in the system. required: - display_name - email v1InputSpec: type: object properties: selection: $ref: "#/components/schemas/v1SelectionInput" description: |- How a person supplies a typed answer. Concrete controls and layout belong to the renderer. No option carries follow-up fields or executable behavior. v1AutomationBookConnectionUpgradeFailure: type: object properties: automation_id: type: string description: The ID of the automation that failed to upgrade. readOnly: true error_message: type: string description: |- Human-readable description of why the upgrade failed for this automation. Other automations in the same request are not affected by this failure. readOnly: true description: |- AutomationBookConnectionUpgradeFailure describes a single automation that could not be upgraded during a BulkUpgradeAutomationBookConnections call. bdkv2ConceptType: type: object properties: scalar_type: $ref: "#/components/schemas/bdkv2ConceptScalarType" optional_type: $ref: "#/components/schemas/bdkv2ConceptOptionalType" list_type: $ref: "#/components/schemas/bdkv2ConceptListType" dictionary_type: $ref: "#/components/schemas/bdkv2ConceptDictionaryType" table_type: $ref: "#/components/schemas/bdkv2ConceptTableType" opaque_type: $ref: "#/components/schemas/bdkv2ConceptOpaqueType" any_type: $ref: "#/components/schemas/bdkv2ConceptAnyType" union_type: $ref: "#/components/schemas/bdkv2ConceptUnionType" self_type: $ref: "#/components/schemas/bdkv2ConceptSelfType" sensitive_type: $ref: "#/components/schemas/bdkv2ConceptSensitiveType" enum_type: $ref: "#/components/schemas/bdkv2ConceptEnumType" bdkv2DictionaryValue: type: object properties: fields: type: array items: $ref: "#/components/schemas/bdkv2DictionaryValueField" title: All the fields alongside their values in the dictionary is_a: type: array items: $ref: "#/components/schemas/bdkv2NounPhrase" title: Is a replationships for the dictionary title: Value to be used when the type is dictionary bdkv2ExampleDescriptor: type: object properties: description: type: string title: The description of the example snippet: type: string title: The example snippet v1ExceptionCluster: type: object properties: name: type: string description: |- {cluster} is an OPAQUE token. Pass it (the last path segment) to the `cluster_key` filter field on ListExceptions to list this cluster's members. Do NOT parse or construct it: it currently encodes the automation, the version and the normalised label, and will encode a stored cluster id once clusters become real resources. title: |- The cluster address. Format: organizations/{organization_id}/workspaces/{workspace_id}/exceptionClusters/{cluster} cluster: type: string description: |- The generic symptom label shared by every member, taken from the representative -- the headline a client shows on the row. Never an identifier; two wordings of one symptom are two clusters. Empty for single-exception clusters whose exception pre-dates cluster generation; clients fall back to the member's own title. automation: type: string description: |- The automation these exceptions occurred on. Matches Exception.automation, which carries the raw automation id. automation_version: type: string description: |- The automation version these exceptions ran on (e.g. "1.0"). Empty when the run carried no version. Part of the cluster identity: the same symptom before and after a fix shipped is two problems, and merging them would hide a regression behind a growing count. member_count: type: integer format: int32 description: Number of exceptions in this cluster, after the request filter. held_count: type: integer format: int32 description: |- How many of those members are still PENDING. Less than member_count when some have settled -- which is what a bulk action moves, since only PENDING exceptions can be archived or retried. oldest_create_time: type: string format: date-time description: |- Creation time of the oldest member. Paired with newest_create_time this is the span the cluster covers, which answers "is this still happening". newest_create_time: type: string format: date-time description: Creation time of the newest member. last_activity_time: type: string format: date-time description: Most recent update to any member. What CLUSTER_ORDER_RECENCY sorts on. representative: type: string description: |- The member to work: the oldest still-held exception, or the oldest member when none are held. Working one that has already settled wastes the operator's turn. Chosen server-side rather than by the client, because the client sees only the members it has fetched: on a cluster larger than one page its own "first member" would be the wrong exception. Format: organizations/{organization_id}/workspaces/{workspace_id}/exceptions/{exception_id} description: |- A group of exceptions that failed the same way on the same automation version -- one row per problem rather than one per stopped run. Not a resource: clusters are computed from Exception.cluster at read time and have no stored identity, so `name` is a system-maintained address rather than an addressable resource. ExceptionGroup sets the same precedent. bdkv2Column: type: object properties: values: type: array items: $ref: "#/components/schemas/bdkv2Value" name: type: string v1CodeInput: type: object properties: name: type: string description: Parameter name from the main() function signature. type: $ref: "#/components/schemas/v1ValueType" description: type: string description: "Description from the main() docstring Args: section (join by name)." description: |- CodeInput represents a single input parameter derived from the main() function signature. 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. Format: permissionTemplates/{permission_template} title: type: string description: |- Human-readable title of the permission (e.g., "automation:read"). Mirrors 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 "DELETE". The raw verb as stored on the template, NOT the CRUD `Action` enum: that enum collapses PATCH and PUT into ACTION_UPDATE, and a client cannot reconstruct which one a `Role.permissions` entry refers to. Clients also use this to group permissions as read (GET) versus write. resource_path: type: string description: |- The resource path pattern this permission applies to, with placeholders (e.g., "/api/v1/organizations/{organization_id}/workspaces/{workspace_id}"). `action` and `resource_path` composed as "{action}:{resource_path}" give the exact strings Role.permissions and CustomRole.permissions carry, which is 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. "build-and-fleet". Mirrors PermissionTemplate.category. A KEY, not a display label: clients own the key-to-label mapping, so a section can be renamed, reordered or translated without a chart change in every service that ships permissions under it. Empty means UNCLASSIFIED, and clients should group those under a heading of their own choosing ("Other") rather than hiding them. An uncategorised permission is still perfectly grantable, and a visibly large Other section is what prompts someone to classify it — hiding them makes the omission invisible instead. Carried here specifically so a role builder can group the list in ONE call. Without it the only source is ListPermissionTemplates, forcing a second request and a join on permissionTemplates/{id}. description: |- A Permission is a single grantable permission, as presented to clients. A projection of a PermissionTemplate carrying only what a client needs to display it and to grant it. It deliberately omits `pat_eligible`: that field is a PAT revocation mechanism gated on the global schema version, and mixing it into a display payload would invite clients to cache it without the version (see AGENTS.md, "Global schema version and the authorization snapshot"). v1ArgumentCapture: type: object properties: response_field: type: string description: Dotted path into the token JSON response, e.g. `authed_user.id`. token_claim: $ref: "#/components/schemas/v1TokenClaim" description: Where a captured argument value is read from within a token response. v1NoRecording: type: object description: |- Mode: NoRecording Starts a fresh execution without recording side-effects. bdkv2ConceptOptionalType: type: object properties: inner: $ref: "#/components/schemas/bdkv2ConceptType" bdkv1FileValue: type: object properties: remote: type: string inline: $ref: "#/components/schemas/bdkv1File" title: A file value represents a file that can be either inline or remote v1TokenClaim: type: object properties: token_field: type: string description: Which response field holds the JWT, e.g. `id_token` or `access_token`. claim: type: string description: Claim name to read from the JWT payload, e.g. `tid`. v1SecretTypeKind: type: object properties: generic: $ref: "#/components/schemas/v1GenericKind" api_key: $ref: "#/components/schemas/v1ApiKeyKind" basic: $ref: "#/components/schemas/v1BasicKind" oauth: $ref: "#/components/schemas/v1OAuthKind" description: |- Discriminated union — new kinds are added as additive `oneof` arms when they ship. OAuth is a single, provider-agnostic kind: all provider behavior lives in the `OAuthApp` recipe (endpoints, scopes, params, templating), not in the kind. bdkv2BookAuthenticationDescriptor: type: object properties: custom: $ref: "#/components/schemas/bdkv2BookCustomAuthenticationDescriptor" oauth: $ref: "#/components/schemas/bdkv2BookOAuthAuthenticationDescriptor" secret_type_id: type: string description: |- Optional secret type id this auth method's credential conforms to. Lets a book share a credential shape across books/services (e.g. "anthropic_api_key") instead of the per-book default. When unset, the default `bdk.{book}.{authId}` is used. Lives on the wrapper (not per-variant) so it covers custom and oauth alike. v1UpdateGuideRequest: type: object properties: guide: $ref: "#/components/schemas/v1Guide" update_mask: type: string description: |- Explicit nonempty mask over title, body, scope, examples and state. work_item is immutable; etag is a precondition, not a mutable field. Updating examples replaces the entire list. Other paths are rejected. description: UpdateGuideRequest contains the guide to change and which fields to change. required: - guide - update_mask bdkv1ListValue: type: object properties: values: type: array items: $ref: "#/components/schemas/bdkv1Value" title: All the values inside the list title: A collection of values v1SourceMapEntry: type: object properties: step_label: type: string description: Hierarchical step label (e.g. "1", "1.2", "2.1.3"). source_location: $ref: "#/components/schemas/commonv1Location" description: SourceMapEntry maps a single AOP step to its location in the original SPy source. bdkv2NounPhrases: type: object properties: noun_phrases: type: array items: $ref: "#/components/schemas/bdkv2NounPhrase" v1ExceptionAssigneeCount: type: object properties: assignee: type: string description: |- The assignee resource name. Format: users/{user} Empty string represents unassigned exceptions. readOnly: true count: type: integer format: int32 description: Number of exceptions assigned to this user (or unassigned if assignee is empty). description: Exception count for a specific assignee. bdkv1File: type: object properties: file_name: type: string title: The name of the file content: type: string format: byte title: Content of the file as a byte stream bdkv2ConceptListType: type: object properties: inner: $ref: "#/components/schemas/bdkv2ConceptType" v2SpyArgumentDescriptor: type: object properties: name: type: string title: SPy keyword-argument name type: $ref: "#/components/schemas/bdkv2ConceptType" description: type: string title: Description of the argument required: type: boolean title: False if the argument can be omitted from the call default_value: $ref: "#/components/schemas/bdkv2Value" title: An argument of a SpySignatureDescriptor v1SecretPayload: type: object properties: fields: type: array items: $ref: "#/components/schemas/v1SecretPayloadField" description: |- Typed secret payload — one entry per field declared in the secret's `SecretType.schema`. Carried over the wire by `AddSecretVersion` and `AccessSecretVersion`; gringotts serializes to JSON before persisting. v1RunAnswer: type: object properties: invocation_id: type: string description: Identity of the ask invocation that was answered. readOnly: true question_key: type: string description: Author-supplied key of the recurring question. readOnly: true prompt: type: string description: The original question shown to the person. readOnly: true form: $ref: "#/components/schemas/v1FormSpec" values: type: object additionalProperties: $ref: "#/components/schemas/commonv1Value" description: The values accepted for the form fields. readOnly: true submit_time: type: string format: date-time description: When the answer was durably accepted. readOnly: true evidence: type: object additionalProperties: $ref: "#/components/schemas/commonv1Value" description: Read-only evidence frozen with the original question. readOnly: true description: A durable accepted answer and the frozen question it answered. v1InventoryEntry: type: object properties: reference: type: object additionalProperties: type: string description: Backend-specific reference. Opaque — pass straight back to AdoptSecret. display_name: type: string description: Human-readable identifier (typically the last path segment). already_managed: type: boolean description: True if a GringottsSecret already wraps this entry. version_count: type: integer format: int64 description: Version count if the backend tracks it. Absent for backends that don't. v1DecisionOutcome: type: string enum: - DECISION_OUTCOME_UNSPECIFIED - DECISION_OUTCOME_APPLIED - DECISION_OUTCOME_REJECTED default: DECISION_OUTCOME_UNSPECIFIED description: |- DecisionOutcome is a source's terminal result for a specific dispatch. - DECISION_OUTCOME_UNSPECIFIED: Not a terminal result; callers must select an outcome. - DECISION_OUTCOME_APPLIED: The requested action was committed or durably scheduled by the source. This does not assert that the downstream workflow succeeded. - DECISION_OUTCOME_REJECTED: The source definitively refused the decision. A reason is required. bdkv2ConnectionRequired: type: string enum: - Optional - Always - Never default: Optional title: Connection required bdkv2ConceptAnyType: type: object v1ParamEdit: type: object properties: path: type: string description: A value-slot path from IdentifyStepValueSlots. value: description: The new literal value. description: "A single param edit: set the literal at `path` to `value`." required: - path - value v1InputContext: type: object properties: form: $ref: "#/components/schemas/v1FormSpec" response: $ref: "#/components/schemas/v1InputResponse" description: |- A human-input form paired with its response. The form preserves the meaning of values after form edits or membership changes. v1SortDirection: type: string enum: - SORT_DIRECTION_UNSPECIFIED - SORT_DIRECTION_ASCENDING - SORT_DIRECTION_DESCENDING default: SORT_DIRECTION_UNSPECIFIED description: |- Direction of a single-column sort. - SORT_DIRECTION_UNSPECIFIED: Default; ascending. - SORT_DIRECTION_ASCENDING: Smallest value first. - SORT_DIRECTION_DESCENDING: Largest value first. v1SecretSchema: type: object properties: fields: type: array items: $ref: "#/components/schemas/v1ValueDictionaryTypeField" description: |- List of typed fields. Wrap a field's `value` in `common.v1.ValueOptionalType` to mark it optional, in `common.v1.ValueSensitiveType` to mark it as redacted on read. bdkv2ConceptTableType: type: object properties: columns: type: array items: $ref: "#/components/schemas/bdkv2ConceptTableTypeColumn" description: type: string v1ImportFirstRowMode: type: string enum: - IMPORT_FIRST_ROW_MODE_UNSPECIFIED - IMPORT_FIRST_ROW_MODE_HEADER - IMPORT_FIRST_ROW_MODE_DATA default: IMPORT_FIRST_ROW_MODE_UNSPECIFIED description: |- How to interpret the first row of a delimited source file. - IMPORT_FIRST_ROW_MODE_UNSPECIFIED: Unspecified; the server treats this as HEADER (the first row holds column names). - IMPORT_FIRST_ROW_MODE_HEADER: The first row contains column names. - IMPORT_FIRST_ROW_MODE_DATA: The first row contains data; column names are generated (column_1, ...). bdkv2ConceptUnionType: type: object properties: inners: type: array items: $ref: "#/components/schemas/bdkv2ConceptType" v1ValueSlot: type: object properties: path: type: string description: Stable address for this slot; also the PromoteParamsToCode edit key. value: description: Current value (null for a computed slot). slot_type: type: string description: "Widget/format hint: money/number/text/date/status/rule/bool/enum." label: type: string description: Human-readable label (arg / field name). editability: $ref: "#/components/schemas/ValueSlotEditability" location: $ref: "#/components/schemas/commonv1Location" description: |- An editable value in a step, derived from the Jarvis CodeManifest (a step arg / external-call CallArg). Step-testing primitive (with IdentifyStepValueSlots, BuildStepHarness, PromoteParamsToCode) — eval execution + scoring live in Alfred. bdkv2BinaryOperator: type: string enum: - BinaryOperatorAnd - BinaryOperatorOr - BinaryOperatorEquals - BinaryOperatorNotEquals - BinaryOperatorIn - BinaryOperatorHas - BinaryOperatorLessThan - BinaryOperatorGreaterThan - BinaryOperatorLessThanOrEqual - BinaryOperatorGreaterThanOrEqual default: BinaryOperatorAnd v2PollInstanceStatus: type: object properties: state: $ref: "#/components/schemas/v2PollInstanceState" state_category: $ref: "#/components/schemas/v2PollInstanceStateCategory" reason: type: string title: Human-readable message providing additional details about the current state last_updated: type: string title: RFC 3339 timestamp of when the status was last updated last_checkpoint: type: string title: ID of the last processed entry, used to resume polling after restart title: Status information for a PollInstance v1ReplayRecord: type: object properties: execution_id: type: string description: The ID of the execution to replay from. description: |- Mode: ReplayRecord Replays side-effects from a previous execution and records any new interactions. bdkv2UnaryExpression: type: object properties: operator: $ref: "#/components/schemas/bdkv2UnaryOperator" inner: $ref: "#/components/schemas/bdkv2Expression" bdkv2QuestionDescriptor: type: object properties: noun_phrases: $ref: "#/components/schemas/bdkv2NounPhrases" type: $ref: "#/components/schemas/bdkv2ConceptType" bdkv2ConceptScalarType: type: string enum: - ConceptScalarTypeConceptual - ConceptScalarTypeText - ConceptScalarTypeNumber - ConceptScalarTypeBoolean - ConceptScalarTypeDatetime - ConceptScalarTypeDate - ConceptScalarTypeTime - ConceptScalarTypeFile - ConceptScalarTypeUUID default: ConceptScalarTypeConceptual title: Supported concept types SecretVersionState: type: string enum: - STATE_UNSPECIFIED - ENABLED - DISABLED - DESTROYED default: STATE_UNSPECIFIED bdkv2BookProcedureSignature: type: object properties: english: type: string verbs: type: array items: type: string title: Verb of the signature object: $ref: "#/components/schemas/bdkv2NounPhrases" preposition: type: string title: Preposition target: $ref: "#/components/schemas/bdkv2NounPhrases" outputs: type: array items: $ref: "#/components/schemas/bdkv2NounPhrases" title: Outputs proper_nouns: type: array items: type: string title: All the proper nouns that appear on this signature bdkv1DictionaryValue: type: object properties: fields: type: array items: $ref: "#/components/schemas/bdkv1DictionaryValueField" title: All the fields alongside their values in the dictionary is_a: type: array items: $ref: "#/components/schemas/bdkv1NounPhrase" title: Is a replationships for the dictionary title: Value to be used when the type is dictionary bdkv2ConceptSelfType: type: object v1FunctionNode: type: object properties: name: type: string description: Function name. docstring: type: string description: |- Verbatim docstring from the function definition. Empty string when the function has no docstring (triggers a warning). location: $ref: "#/components/schemas/commonv1Location" calls: type: array items: $ref: "#/components/schemas/v1FunctionNode" description: |- User-defined functions called within this function, in call order. Recursive calls stop at cycle boundaries (no loops in the tree). description: |- FunctionNode represents a user-defined function in the recursive call tree. The tree preserves call order within each function body, enabling UI sub-step progress tracking and exception breadcrumbs. Shared functions called from multiple steps appear in each step's tree at their respective call sites (each appearance = a distinct runtime invocation). bdkv2ConceptSensitiveType: type: object properties: inner: $ref: "#/components/schemas/bdkv2ConceptType" v1WorkUnitStatus: type: string enum: - WORK_UNIT_STATUS_UNSPECIFIED - WORK_UNIT_STATUS_WAITING_FOR_INPUT - WORK_UNIT_STATUS_ANSWERED - WORK_UNIT_STATUS_DISMISSED - WORK_UNIT_STATUS_WITHDRAWN - WORK_UNIT_STATUS_PROCESSING default: WORK_UNIT_STATUS_UNSPECIFIED description: |- WorkUnitStatus records attention and final resolution independently of delivery. - WORK_UNIT_STATUS_UNSPECIFIED: Default value; not returned for an existing resource. - WORK_UNIT_STATUS_WAITING_FOR_INPUT: Waiting for intermediate input or a direct final answer: an item input_form exists and input is unaccepted, or no input_form exists and the kind does not require preparation. Saving either draft leaves status unchanged. - WORK_UNIT_STATUS_ANSWERED: Final submission and its delivery obligation are durable. - WORK_UNIT_STATUS_DISMISSED: Locally dismissed by item archival, arrival or rekey into an archived item. Unarchive restores it unless the source or operator has withdrawn it. - WORK_UNIT_STATUS_WITHDRAWN: Source or operator ended the occurrence without an answer. - WORK_UNIT_STATUS_PROCESSING: Analysis or decision preparation is pending; no current human request. Includes work without an input_form whose kind requires preparation, and final-answer preparation after intermediate input acceptance. bdkv2ConceptEnumType: type: object properties: is_a: type: array items: $ref: "#/components/schemas/bdkv2NounPhrase" members: type: array items: $ref: "#/components/schemas/bdkv2ConceptEnumTypeMember" description: type: string bdkv2ConceptOpaqueType: type: object properties: is_a: type: array items: $ref: "#/components/schemas/bdkv2NounPhrase" description: type: string v1Comparison: type: object properties: field: type: string description: Column to compare, named verbatim. operator: $ref: "#/components/schemas/v1ComparisonOperator" value: $ref: "#/components/schemas/commonv1Value" description: A comparison of a column against a literal value. required: - field - operator - value bdkv2UnaryOperator: type: string enum: - UnaryOperatorNot - UnaryOperatorExists default: UnaryOperatorNot v1GenericKind: type: object description: |- Schema-only; no acquisition behavior. The default for arbitrary credential shapes. v1AgentConnection: type: object properties: connection_id: type: string description: The id of the connection the agent's tool source points at (e.g. "idp-jxnvp"). readOnly: true book_name: type: string description: The book name that provides this connection type (e.g. "google-sheets"). readOnly: true book_version: type: string description: The book version the connection is pinned to, when the tool source reports one. readOnly: true display_name: type: string description: The connection display name as it appears in the agent's source workspace. readOnly: true description: |- A book connection attached directly to an agent through one of its `connection` tool sources. This describes the agent's own tool wiring, not any automation it calls: it is read from the agent's effective tool catalog and is unrelated to MissingConnection, which describes connection aliases referenced by an automation's phase code. v1OAuthKind: type: object description: |- OAuth2 credentials (any provider). How the flow runs is fully described by the `OAuthApp`'s `OAuthConfig` recipe — gringotts has no provider-specific code. v1BackendHealth: type: string enum: - BACKEND_HEALTH_UNSPECIFIED - BACKEND_HEALTH_HEALTHY - BACKEND_HEALTH_DEGRADED - BACKEND_HEALTH_UNHEALTHY - BACKEND_HEALTH_UNKNOWN default: BACKEND_HEALTH_UNSPECIFIED v1IdentifyingDetail: type: object properties: label: type: string description: Business-facing label, for example "Invoice". value: type: string description: Nonempty display fallback, for example "INV-1042" or "invoice.pdf". evidence_ref: type: string description: |- Optional exact top-level key in the same work unit's evidence map. This is neither a resource URI nor an expression. Readers use value when absent, unresolved or unavailable; an invalid reference never rejects work. description: |- A source-authored identifying fact for a unit's compact heading. Displayed in source order, with optional access to frozen evidence. v1Audit: type: object properties: external_calls: type: array items: $ref: "#/components/schemas/v1ExternalCall" description: |- Every kognitos...(...) call reachable transitively from this step's function. literals: type: array items: $ref: "#/components/schemas/v1Literal" description: |- Every string and numeric literal in the transitive call subtree. Includes trivial values (0, "", None, etc.) — no filtering applied. collections: type: array items: $ref: "#/components/schemas/v1CollectionAccess" description: |- Every first-class collection access reachable transitively from this step's function. Reports the raw method invoked; consumers (e.g. Grimoire) classify each access as a read or a write. assets: type: array items: $ref: "#/components/schemas/v1AssetAccess" description: |- Every read-only asset (file) reference reachable transitively from this step's function, via the file("bishop://…") constructor. Reports the raw URI as written; consumers resolve it. config_accesses: type: array items: $ref: "#/components/schemas/v1ConfigAccess" description: |- Every kognitos.config. read reachable transitively from this step's function (comparisons, computation, .format() templates, call kwargs). Config is read-only, so every access is a read. stops: type: array items: $ref: "#/components/schemas/v1Stop" description: |- Programmatic stop() sites reachable transitively from this step (an outcome-type site). A non-empty list means the step may terminate the run early as a successful completion (not a "stopped" run). Presence is reachability-based, not "always fires" — stop() is typically guarded by a conditional, which static analysis does not evaluate. input_accesses: type: array items: $ref: "#/components/schemas/v1InputAccess" description: |- Every main() input supplied directly as a positional or keyword argument to this step's call in main(). Each entry identifies the input and its argument location. description: |- Audit is a flat checklist of the reachable sites — dependencies and outcomes — for a step, collected transitively from the step's function through all nested user-defined calls. v1DownloadFormat: type: string enum: - DOWNLOAD_FORMAT_UNSPECIFIED - DOWNLOAD_FORMAT_ARROW - DOWNLOAD_FORMAT_CSV - DOWNLOAD_FORMAT_JSON - DOWNLOAD_FORMAT_TXT default: DOWNLOAD_FORMAT_UNSPECIFIED description: |- Download format for file content. Specifies the desired serialization format when downloading file content. - DOWNLOAD_FORMAT_UNSPECIFIED: Unspecified format; server will apply default behavior (Arrow). - DOWNLOAD_FORMAT_ARROW: Apache Arrow IPC format. - DOWNLOAD_FORMAT_CSV: Comma-separated values format. - DOWNLOAD_FORMAT_JSON: JSON format. - DOWNLOAD_FORMAT_TXT: Plain text format. v1BasicKind: type: object description: Static username/password credentials, validated by the schema alone. v1ExecutionStatus: type: object properties: execution_id: type: string title: Unique identifier for the execution update_time: type: string format: date-time title: When this status update was generated started: $ref: "#/components/schemas/jarvisexecution_statusv1ExecutionStarted" in_progress: $ref: "#/components/schemas/v1ExecutionInProgress" completed: $ref: "#/components/schemas/jarvisexecution_statusv1ExecutionCompleted" stopped: $ref: "#/components/schemas/jarvisexecution_statusv1ExecutionStopped" failed: $ref: "#/components/schemas/jarvisexecution_statusv1ExecutionFailed" description: |- ExecutionStatus represents the current state of a Jarvis code execution. This message is sent periodically to provide updates on execution progress, completion, or failure conditions. Each status update includes a timestamp and the specific status information. v1Stop: type: object properties: location: $ref: "#/components/schemas/commonv1Location" containing_function: type: string description: The user-defined function where the stop() appears. description: |- Stop represents a programmatic stop() call reachable from a step's transitive call graph — a point where the run may complete early. A stop() ends the run as a successful completion, not a "stopped" run. bdkv1SensitiveValue: type: object properties: value: $ref: "#/components/schemas/bdkv1Value" title: A sensitive value is any value marked as sensitive (to prevent exposure) bdkv1Table: type: object properties: columns: type: array items: $ref: "#/components/schemas/bdkv1Column" description: |- A table is a column-oriented structure. All the values inside each column must be of equal length. commonv1Location: type: object properties: start_byte: type: string format: int64 title: Starting Byte of the span, It will be zero-based end_byte: type: string format: int64 title: Ending Byte(exclusive) of the span, It will be zero-based start_position: $ref: "#/components/schemas/v1Position" end_position: $ref: "#/components/schemas/v1Position" description: |- Location represents a generic span within some underlying content. It specifies the starting byte offset and the ending byte offset (exclusive) of the span. This can be used for pointing to regions in files, buffers, logs, messages, or any other byte-addressable resource. bdkv2Label: type: object properties: key: type: string title: The key of the key-value pair value: type: string title: The value of the key-value pair v1AssetAccess: type: object properties: uri: type: string description: Raw bishop:// URI exactly as written in the automation code. location: $ref: "#/components/schemas/commonv1Location" description: |- AssetAccess represents a read-only asset (file) reference found in the transitive call graph of a step, via the file("bishop://…") constructor. bdkv2File: type: object properties: file_name: type: string title: The name of the file content: type: string format: byte title: Content of the file as a byte stream v1Param: type: object properties: name: type: string description: Parameter name from the function signature. type: $ref: "#/components/schemas/v1ValueType" description: type: string description: "Description from the docstring Args: entry (join by name)." description: |- Param represents a single named, typed, documented parameter of a step function (docstring Args: joined to the signature annotation). v1CollectionUsageType: type: string enum: - COLLECTION_USAGE_TYPE_UNSPECIFIED - COLLECTION_USAGE_TYPE_READ - COLLECTION_USAGE_TYPE_WRITE default: COLLECTION_USAGE_TYPE_UNSPECIFIED description: |- How an automation uses a collection, derived from the collection access methods (get / insert / update / delete) recorded in its code manifest. Any write access classifies the collection as WRITE (write subsumes read). - COLLECTION_USAGE_TYPE_UNSPECIFIED: Default; usage could not be determined. - COLLECTION_USAGE_TYPE_READ: Read-only accesses (e.g. get). - COLLECTION_USAGE_TYPE_WRITE: At least one write access (e.g. insert / update / delete). v1Position: type: object properties: line: type: integer format: int32 description: 0-based line number. column: type: integer format: int32 description: 0-based column offset (bytes from line start). description: A position in a text document expressed as 0-based line and column. bdkv1OpaqueValue: type: object properties: content: type: string format: byte title: Content of the opaque value is_a: type: array items: $ref: "#/components/schemas/bdkv1NounPhrase" title: Is a replationships for the opaque bdkv1Column: type: object properties: values: type: array items: $ref: "#/components/schemas/bdkv1Value" name: type: string TransitionGuideEntryStateRequestAction: type: string enum: - ACTION_UNSPECIFIED - ACTION_APPROVE - ACTION_REJECT - ACTION_ARCHIVE default: ACTION_UNSPECIFIED description: |- Actions that can be performed on a guide entry. - ACTION_UNSPECIFIED: Action is not specified. - ACTION_APPROVE: Approve the guide entry. Transitions from PENDING_APPROVAL to APPROVED. Approved guide entries can be used by the agent to resolve exceptions. - ACTION_REJECT: Reject the guide entry. Transitions from PENDING_APPROVAL to REJECTED. Rejected guide entries will not be used by the agent. - ACTION_ARCHIVE: Archive the guide entry. Can be performed from any state. Archived guide entries are retained for historical purposes but not used by the agent. v1InputResponse: type: object properties: values: type: object additionalProperties: $ref: "#/components/schemas/commonv1Value" description: |- Current values. Drafts may omit required fields, but supplied values must satisfy the published form. Empty values clear the draft. Unknown keys fail. readOnly: true etag: type: string description: |- Opaque concurrency token. Changes on edits, acceptance, revocation and unarchive or form changes. Never reused after clearing a response or rekey. Clients must return the token they actually read. readOnly: true updated_by: type: string description: Actor who last edited values. Empty for a newly created, untouched draft. readOnly: true update_time: type: string format: date-time description: Time of the latest draft or acceptance change. readOnly: true accepted_by: type: string description: |- Authenticated actor who explicitly accepted these values; empty if not accepted. User attribution does not distinguish a human from their agent. readOnly: true accept_time: type: string format: date-time description: |- Present only while acceptance is valid. Revoke acceptance before editing. Form edits, rekey and unarchive invalidate acceptance; final submission prevents editing. readOnly: true description: |- Editable per-unit human input, with explicit acceptance separate from filling. Acceptance permits final-answer preparation; it is not a final submission. bdkv2ConceptTableTypeColumn: type: object properties: key: type: string value: $ref: "#/components/schemas/bdkv2ConceptType" description: type: string jarvisexecution_statusv1ExecutionStopped: type: object properties: user_stopped: $ref: "#/components/schemas/jarvisexecution_statusv1UserStopped" waiting_on_book: $ref: "#/components/schemas/jarvisexecution_statusv1WaitingOnBook" waiting_on_timer: $ref: "#/components/schemas/jarvisexecution_statusv1WaitingOnTimer" program_stopped: $ref: "#/components/schemas/jarvisexecution_statusv1ProgramStopped" waiting_on_book_connection: $ref: "#/components/schemas/jarvisexecution_statusv1WaitingOnBookConnection" description: |- ExecutionStopped indicates that the execution was stopped before completion due to a specific reason. v1UserState: type: string enum: - USER_STATE_UNSPECIFIED - USER_STATE_ACTIVE - USER_STATE_DEACTIVATED default: USER_STATE_UNSPECIFIED description: |- Today's flow re-uses the existing soft-delete column rather than introducing a new column: `state = DEACTIVATED` iff `deleted_at IS NOT NULL`. Surfaced output-only so admin UIs can render a "Deactivated" badge alongside the user row. - USER_STATE_UNSPECIFIED: Unspecified — older clients that don't populate the field. - USER_STATE_ACTIVE: User is active. - USER_STATE_DEACTIVATED: User has been deactivated (soft-deleted). Authentication is blocked. title: User activation state, derived from `users.deleted_at`. (MAN-3390) v1SecretPayloadField: type: object properties: key: type: string value: $ref: "#/components/schemas/commonv1Value" v1ConfigAccess: type: object properties: name: type: string description: Config name, same format as the in kognitos.config.. location: $ref: "#/components/schemas/commonv1Location" description: |- ConfigAccess represents a kognitos.config. read reachable transitively from a step. Read-only; the resolved value is joined from the config schema. bdkv2ConceptDictionaryType: type: object properties: is_a: type: array items: $ref: "#/components/schemas/bdkv2NounPhrase" fields: type: array items: $ref: "#/components/schemas/bdkv2ConceptDictionaryTypeField" description: type: string v1OAuthPayload: type: object properties: scopes: type: array items: type: string description: |- Requested scopes. Empty = use the OAuth app's configured `scopes`; non-empty *overrides* them (it does not augment). arguments: type: object additionalProperties: type: string description: |- Values for the OAuth app's declared template `arguments` (e.g. `tenant`), substituted into the `{arg}` placeholders in the endpoints. description: |- Inputs that begin an OAuth authorization-code flow for an OAuth-kind secret. Not token data — it carries what's needed to build the authorize URL; the tokens land later, on the callback. v1FuzzyMatch: type: object properties: field: type: string description: Column to match, named verbatim. query: type: string description: Text to match the column against. threshold: type: number format: double description: Minimum similarity to accept, in [0.0, 1.0]. Defaults to 0.8 when unset. description: An approximate (typo-tolerant, case-insensitive) text match on a column. required: - field - query bdkv2BookCustomAuthenticationDescriptor: type: object properties: id: type: string description: |- Since books can have multiple authentication mechanisms there is and ID to differentiate each mechanism. credentials: type: array items: $ref: "#/components/schemas/bdkv2CredentialDescriptor" title: Credentials required to perform authentication description: type: string title: A description of the authentication name: type: string title: A name for the authentication noun_phrase: $ref: "#/components/schemas/bdkv2NounPhrase" preferred: type: boolean title: If this is a preferred authentication method deprecated: type: boolean title: If this authentication method is deprecated ValueSlotEditability: type: string enum: - EDITABILITY_UNSPECIFIED - EDITABILITY_LITERAL - EDITABILITY_COMPUTED default: EDITABILITY_UNSPECIFIED description: |- Whether this slot's value can be edited, mirroring the manifest CallArg source classification. - EDITABILITY_UNSPECIFIED: Default; unset. - EDITABILITY_LITERAL: An inline literal — editable (PromoteParamsToCode). - EDITABILITY_COMPUTED: A computed value (variable/expression) — surfaced read-only. v1LogicalOperator: type: string enum: - LOGICAL_OPERATOR_UNSPECIFIED - LOGICAL_OPERATOR_AND - LOGICAL_OPERATOR_OR default: LOGICAL_OPERATOR_UNSPECIFIED description: |- Logical operator joining the operands of a group. - LOGICAL_OPERATOR_UNSPECIFIED: Default; unset operator. - LOGICAL_OPERATOR_AND: All operands must match. - LOGICAL_OPERATOR_OR: At least one operand must match. v1RecordOnly: type: object description: |- Mode: RecordOnly Starts a fresh execution and records side-effects (Book calls). bdkv2BookOAuthAuthenticationDescriptor: type: object properties: id: type: string description: |- Since books can have multiple authentication mechanisms there is and ID to differentiate each mechanism. provider: $ref: "#/components/schemas/bdkv2OAuthProvider" flows: type: array items: $ref: "#/components/schemas/bdkv2OAuthFlow" title: Supported OAuth flows authorize_endpoint: type: string title: Authorize endpoint token_endpoint: type: string title: Token endpoint scope: type: array items: type: string title: Scopes name: type: string title: A name for the authentication arguments: type: array items: $ref: "#/components/schemas/bdkv2OAuthArgumentDescriptor" title: |- Additional arguments which are not part of the OAuth specification but are required for the authentication to work (such as tenant_id) credentials: type: array items: $ref: "#/components/schemas/bdkv2CredentialDescriptor" title: Credential descriptors preferred: type: boolean title: If this is a preferred authentication method parameter_mapping: type: object additionalProperties: type: string description: |- Optional mapping of standard OAuth parameter names to provider-specific names. For example, Slack requires scopes to be sent as "user_scope" instead of "scope" on the authorize URL: { "scope": "user_scope" } The runtime uses this to rename parameters when constructing the authorize and token exchange requests. deprecated: type: boolean title: If this authentication method is deprecated bdkv2ConceptEnumTypeMember: type: object properties: name: type: string noun_phrase: $ref: "#/components/schemas/bdkv2NounPhrase" description: type: string bdkv1NounPhrase: type: object properties: modifiers: type: array items: type: string title: Optional adjectives attached to the noun head: type: string title: Noun of the phrase v1ApiKeyKind: type: object description: Static API-key credentials, validated by the schema alone. v1InputAccess: type: object properties: name: type: string description: Input name, matching CodeInput.name in the code manifest. location: $ref: "#/components/schemas/commonv1Location" description: InputAccess represents a main() input supplied directly to a step. v1CollectionAccess: type: object properties: slug_name: type: string description: |- Collection slug as written in the automation code (the human slug, not the resolved collection id). method: type: string description: The collection method invoked (e.g. "get", "insert", "update", "delete"). location: $ref: "#/components/schemas/commonv1Location" description: |- CollectionAccess represents a first-class collection operation found in the transitive call graph of a step. The raw method name is reported as-is; consumers classify it as a read or a write. v2PollInstanceState: type: string enum: - POLL_INSTANCE_STATE_PENDING - POLL_INSTANCE_STATE_READY - POLL_INSTANCE_STATE_FAILED - POLL_INSTANCE_STATE_UNKNOWN default: POLL_INSTANCE_STATE_PENDING title: Possible phases for a PollInstance (Pending, Ready, Failed, Unknown) v1ReplayOnly: type: object properties: execution_id: type: string description: The ID of the execution to replay from. description: |- Mode: ReplayOnly Replays side-effects from a previous execution without recording any new interactions. Useful for deterministic re-runs and debugging where the recording should not be mutated or extended. v1NumberConstraints: type: object properties: minimum: $ref: "#/components/schemas/v1Number" maximum: $ref: "#/components/schemas/v1Number" integer_only: type: boolean description: Require a value with no fractional component. description: Exact decimal restrictions on a numeric answer. bdkv2ConceptDescriptor: type: object properties: noun_phrases: $ref: "#/components/schemas/bdkv2NounPhrases" type: $ref: "#/components/schemas/bdkv2ConceptType" description: type: string title: Description default_value: $ref: "#/components/schemas/bdkv2Value" v1OnboardingState: type: string enum: - ONBOARDING_STATE_UNSPECIFIED - WORKSPACE_CREATION_PENDING - COMPLETED default: ONBOARDING_STATE_UNSPECIFIED description: |- Represents the onboarding state of a user. - ONBOARDING_STATE_UNSPECIFIED: Unspecified onboarding state. - WORKSPACE_CREATION_PENDING: User needs to create a workspace. - COMPLETED: User has completed onboarding. jarvisexecution_statusv1UserStopped: type: object description: UserStopped indicates that the execution was stopped by a user. bdkv2DictionaryValueField: type: object properties: key: type: string value: $ref: "#/components/schemas/bdkv2Value" title: Each key-value pair inside a dictionary v1SelectionInput: type: object properties: options: type: array items: $ref: "#/components/schemas/v1SelectionOption" description: |- Distinct typed values with nonempty labels. May be empty. Each value must satisfy the scalar/element type and applicable field constraints. Numeric equality is decimal equality, so 1 and 1.0 are the same option. min_selections: type: integer format: int64 description: |- Only for list fields. Omitted minimum means zero; omitted maximum means the option count. Bounds must be ordered and, for nonempty option sets, no greater than that count. Empty selections retain bounds for answer validation. Unknown or repeated selections fail. Persist selections in option order, using the declared option values, not user click order or numeric encoding. max_selections: type: integer format: int64 description: Inclusive maximum number of selected options. options_ref: type: string description: |- Exact nonempty top-level WorkUnit.evidence key, not a path or expression. Allowed only in shared human input, mutually exclusive with inline options. Valid evidence is an inline list of distinct scalar values matching the field's scalar/element type and constraints. Inline text wrappers are normalized to text. No remote reads, record projections or coercion occur. Each value is both the displayed choice and the submitted value: text is unchanged, numbers use exact decimal text, booleans use true/false, and dates use YYYY-MM-DD. Empty text has no display label and is invalid as an option. Missing, empty or invalid choices produce an empty selection, not an input error or free entry. Other fields remain usable. Initial values incompatible with the resolved selection are omitted for that unit. description: |- A finite set of offered values. A scalar field selects one value; a list field selects distinct values of its element type. Optional None is absence, never an option. Use inline options or options_ref, not both. Empty selections offer no choices and never enable free entry. Resolved unit input and source answer forms use inline options only. jarvisexecution_statusv1WaitingOnTimer: type: object properties: duration: type: string description: The duration of the timer. description: |- WaitingOnTimer indicates that the execution is stopped because its waiting for a timer to fire. The run manager is expected to resume the execution when the timer fires. v1SelectionOption: type: object properties: label: type: string description: Nonempty display wording, independent of the submitted value. value: $ref: "#/components/schemas/commonv1Value" description: Display wording and the typed value returned when this option is selected. required: - label - value v1ExternalCall: type: object properties: call: type: string description: Dotted path of the book function (e.g. "kognitos.sap.purchase_order.read"). containing_function: type: string description: The user-defined function where this call appears. call_location: $ref: "#/components/schemas/commonv1Location" is_mutating: type: boolean description: Whether the call changes the world (static-analysis-derived). args: type: array items: $ref: "#/components/schemas/v1CallArg" description: The call's keyword arguments, in source order. description: |- ExternalCall represents a book function call found in the transitive call graph of a step. bdkv2OAuthArgumentDescriptor: type: object properties: id: type: string title: Id of the parameter name: type: string title: Name of the parameter description: type: string title: Description of the parameter v1TextConstraints: type: object properties: min_length: type: integer format: int64 description: |- Unicode scalar-value counts, not bytes or UTF-16 code units. No implicit trimming, normalization, pattern evaluation or text transformation. max_length: type: integer format: int64 description: Inclusive maximum length, measured in Unicode scalar values. description: Length restrictions on a text answer. v2PollInstanceStateCategory: type: string enum: - POLL_INSTANCE_STATE_CATEGORY_WARNING - POLL_INSTANCE_STATE_CATEGORY_READY - POLL_INSTANCE_STATE_CATEGORY_FAILED default: POLL_INSTANCE_STATE_CATEGORY_WARNING title: The category/level of the poll instance state jarvisexecution_statusv1ExecutionFailed: type: object properties: error: $ref: "#/components/schemas/v1ExecutionError" description: |- ExecutionFailed indicates that the execution encountered an error and could not complete successfully. jarvisexecution_statusv1WaitingOnBookConnection: type: object properties: connection_id: type: string description: The book connection that is not ready. book_name: type: string description: The name of the book the connection is for. state: type: string description: The state of the book connection when the execution stopped. description: |- WaitingOnBookConnection indicates that the execution is stopped because a book connection it calls is not ready. The run manager resumes the execution once the connection is ready. v1Literal: type: object properties: value: type: string description: The literal value as a string. containing_function: type: string description: The user-defined function where this literal appears. description: |- Literal represents a string or numeric literal found in the transitive call graph of a step. jarvisexecution_statusv1ExecutionStarted: type: object description: ExecutionStarted indicates that Jarvis has started the execution. v1ComparisonOperator: type: string enum: - COMPARISON_OPERATOR_UNSPECIFIED - COMPARISON_OPERATOR_EQUAL - COMPARISON_OPERATOR_NOT_EQUAL - COMPARISON_OPERATOR_LESS_THAN - COMPARISON_OPERATOR_LESS_THAN_OR_EQUAL - COMPARISON_OPERATOR_GREATER_THAN - COMPARISON_OPERATOR_GREATER_THAN_OR_EQUAL - COMPARISON_OPERATOR_HAS - COMPARISON_OPERATOR_IN default: COMPARISON_OPERATOR_UNSPECIFIED description: |- Comparison applied between a column and a literal value. - COMPARISON_OPERATOR_UNSPECIFIED: Default; unset operator. - COMPARISON_OPERATOR_EQUAL: Column equals the value. - COMPARISON_OPERATOR_NOT_EQUAL: Column differs from the value. - COMPARISON_OPERATOR_LESS_THAN: Column is less than the value. - COMPARISON_OPERATOR_LESS_THAN_OR_EQUAL: Column is less than or equal to the value. - COMPARISON_OPERATOR_GREATER_THAN: Column is greater than the value. - COMPARISON_OPERATOR_GREATER_THAN_OR_EQUAL: Column is greater than or equal to the value. - COMPARISON_OPERATOR_HAS: Column contains the value as a substring. - COMPARISON_OPERATOR_IN: Column matches one of the members of a list value. bdkv2OAuthFlow: type: string enum: - OAuthFlowAuthorizationCode - OAuthFlowClientCredentials default: OAuthFlowAuthorizationCode title: Supported OAuth flows jarvisexecution_statusv1ExecutionCompleted: type: object properties: outputs: type: object additionalProperties: $ref: "#/components/schemas/commonv1Value" description: |- Map of named output values set by the set_output() builtin function during execution. Each entry is a name-value pair where the key is the output name (string) and the value is the output value set by calling set_output(name, value). This map will be empty if no set_output() calls were made during execution. return_value: $ref: "#/components/schemas/commonv1Value" description: ExecutionCompleted indicates that Jarvis has successfully completed the execution. bdkv1DictionaryValueField: type: object properties: key: type: string value: $ref: "#/components/schemas/bdkv1Value" title: Each key-value pair inside a dictionary v1CallArg: type: object properties: name: type: string description: Keyword name (e.g. "recipients", "subject"). location: $ref: "#/components/schemas/commonv1Location" type: $ref: "#/components/schemas/v1ValueType" literal: $ref: "#/components/schemas/commonv1Value" config: type: string description: |- Config name (same format as ConfigAccess.name) — the argument reads kognitos.config.. Join to the config schema to resolve its value. description: |- CallArg represents one keyword argument at an external call site. The source oneof classifies the argument's value: an inline literal, a config reference, or — when neither arm is set — a computed value (a variable or expression not known statically). v1ExecutionInProgress: type: object description: |- ExecutionInProgress indicates that Jarvis is still running the execution. This status acts as a heartbeat to confirm that the execution is still running. jarvisexecution_statusv1ProgramStopped: type: object properties: reason: type: string description: The reason the program was stopped. description: ProgramStopped indicates that the execution was stopped by the program. bdkv2OAuthProvider: type: string enum: - OAuthProviderMicrosoft - OAuthProviderGoogle - OAuthProviderGeneric default: OAuthProviderMicrosoft title: Supported OAuth providers bdkv2CredentialDescriptor: type: object properties: id: type: string title: Id of the credential type: $ref: "#/components/schemas/bdkv2CredentialType" label: type: string title: Label that will be displayed to the user during configuration of the book visible: type: boolean description: True if the value is visible to the book, false otherwise. description: type: string title: Description bdkv2ConceptDictionaryTypeField: type: object properties: key: type: string value: $ref: "#/components/schemas/bdkv2ConceptType" description: type: string jarvisexecution_statusv1WaitingOnBook: type: object description: |- WaitingOnBook indicates that the execution is stopped because its waiting on an async book procedure to complete. The run manager is expected to resume the execution when the book procedure completes. bdkv2CredentialType: type: string enum: - CredentialTypeText - CredentialTypeSensitiveText - CredentialTypeSensitiveDictionary default: CredentialTypeText title: Supported configuration types v1ArchivedRunState: type: object description: |- Run has been archived by the user. The run is preserved for historical reference but cannot be modified, resumed, or mutated in any way. v1AwaitingAnswerRunState: type: object properties: invocation_id: type: string description: Identity of the ask() invocation the run is waiting on. readOnly: true question_key: type: string description: Author-supplied key identifying the recurring logical question. readOnly: true prompt: type: string description: The question shown to the person. readOnly: true form: $ref: "#/components/schemas/v1FormSpec" evidence: type: object additionalProperties: $ref: "#/components/schemas/commonV1Value" description: Supporting values frozen with the question. readOnly: true description: |- Run is intentionally waiting for a person to answer an ask() question. This is planned waiting, not a failure or an exception: the run resumes once the question is answered through the authoring experience or Workbench. v1ContentLocation: type: object properties: page_number: type: integer format: int32 description: The 1-based page number, in a paginated document such as a PDF. sheet: type: string description: The name of the sheet, in a spreadsheet. email_part: $ref: "#/components/schemas/v1EmailPart" email_attachment: type: string description: |- The file name of an attachment, in an email file (.eml); the term was found in the attachment's text. description: A location inside a file where the search term was found. v1ContentMatchSource: type: string enum: - CONTENT_MATCH_SOURCE_UNSPECIFIED - CONTENT_MATCH_SOURCE_INPUT - CONTENT_MATCH_SOURCE_OUTPUT - CONTENT_MATCH_SOURCE_TRIGGER - CONTENT_MATCH_SOURCE_STEP_FILE - CONTENT_MATCH_SOURCE_STEP_OUTPUT default: CONTENT_MATCH_SOURCE_UNSPECIFIED description: |- Where in a run a content match was found. More sources may be added; treat a value you do not recognize as an unknown place in the run. - CONTENT_MATCH_SOURCE_UNSPECIFIED: Unspecified source. Not returned by the server. - CONTENT_MATCH_SOURCE_INPUT: A file in the run's inputs (user_inputs). - CONTENT_MATCH_SOURCE_OUTPUT: A file in the run's outputs. - CONTENT_MATCH_SOURCE_TRIGGER: A file in the payload the run was started with, such as an attachment of the email that triggered it, when the file is not also one of the run's inputs. - CONTENT_MATCH_SOURCE_STEP_FILE: A file one of the run's steps used, found through the Run log. - CONTENT_MATCH_SOURCE_STEP_OUTPUT: Text one of the run's steps produced, found through the Run log, such as the fields a document-processing book extracted. display_name names the file the step read, if it read one. v1ContentSkipReason: type: string enum: - CONTENT_SKIP_REASON_UNSPECIFIED - CONTENT_SKIP_REASON_NO_TEXT_LAYER - CONTENT_SKIP_REASON_TOO_LARGE - CONTENT_SKIP_REASON_UNSUPPORTED_FORMAT - CONTENT_SKIP_REASON_ENCRYPTED - CONTENT_SKIP_REASON_FAILED - CONTENT_SKIP_REASON_TOO_MANY_FILES - CONTENT_SKIP_REASON_INACCESSIBLE default: CONTENT_SKIP_REASON_UNSPECIFIED description: |- Why content search will not index one of a run's files. More reasons may be added; treat a value you do not recognize as a file that is not searchable for an unstated reason. - CONTENT_SKIP_REASON_UNSPECIFIED: Unspecified reason. Not returned by the server. - CONTENT_SKIP_REASON_NO_TEXT_LAYER: The file has no text layer, such as an image or a scanned PDF. Content search does not run OCR. - CONTENT_SKIP_REASON_TOO_LARGE: The file is larger than content search reads. A file that is only cut off at a limit is indexed instead, and counted in RunContentCoverage.partially_indexed_file_count. - CONTENT_SKIP_REASON_UNSUPPORTED_FORMAT: Content search cannot read the file's format, such as a legacy Word or PowerPoint document, an Outlook message, or an archive. - CONTENT_SKIP_REASON_ENCRYPTED: The file is password-protected. - CONTENT_SKIP_REASON_FAILED: Reading the file failed and will not be retried, for example because the file is corrupt, or reading it kept crashing or timing out. - CONTENT_SKIP_REASON_TOO_MANY_FILES: The run has more files than content search indexes for a single run, and this file is beyond that limit. - CONTENT_SKIP_REASON_INACCESSIBLE: The file cannot be read from this run: it no longer exists, or the run refers to it somewhere content search does not follow, such as another workspace. v1EmailPart: type: string enum: - EMAIL_PART_UNSPECIFIED - EMAIL_PART_SUBJECT - EMAIL_PART_HEADERS - EMAIL_PART_BODY default: EMAIL_PART_UNSPECIFIED description: |- A part of an email message. - EMAIL_PART_UNSPECIFIED: Unspecified email part. Not returned by the server. - EMAIL_PART_SUBJECT: The subject line. - EMAIL_PART_HEADERS: The headers other than the subject, such as the sender and recipients. - EMAIL_PART_BODY: The message body. v1FileContentMatch: type: object properties: display_name: type: string description: |- The file's name, such as "invoice.pdf". Empty when there is no name: an unnamed file, an offloaded text value (field names it instead), or text a step produced without reading a file. readOnly: true source: $ref: "#/components/schemas/v1ContentMatchSource" field: type: string description: |- For the CONTENT_MATCH_SOURCE_INPUT, _OUTPUT and _TRIGGER sources, the name of the value the match is in, as it appears in the run's inputs, outputs or trigger payload; for a file inside a list or dictionary, the name of the outer value. Empty for the other sources. readOnly: true step_label: type: string description: |- For the CONTENT_MATCH_SOURCE_STEP_FILE and _STEP_OUTPUT sources, a human-readable label for the step as the Run log shows it, such as "Step 4: Extract the invoice fields". Empty for the other sources. readOnly: true locations: type: array items: $ref: "#/components/schemas/v1ContentLocation" description: |- Where in the file the term was found, in document order. Holds at most a server-chosen number of locations, so a term found on many pages lists only the first of them. Empty when the format has no finer location, as with plain text, CSV and Word documents, and for text a step produced. readOnly: true description: |- One place in a run whose text contains the search term: a file, or text one of the run's steps produced. v1FunctionCallContext: type: object properties: function_name: type: string title: The name of the function that was called input_args: type: object additionalProperties: $ref: "#/components/schemas/commonV1Value" title: The named input parameters passed to the function (parameter name → value) return_value: $ref: "#/components/schemas/commonV1Value" description: |- FunctionCallContext captures the semantic details of a function call: the function name, its named arguments, and the return value. Populated for any statement whose execution involved a function call (user-defined, builtin, or book function). v1InvitationDirection: type: string enum: - INVITATION_DIRECTION_UNSPECIFIED - INVITATION_DIRECTION_INVITE - INVITATION_DIRECTION_REQUEST default: INVITATION_DIRECTION_UNSPECIFIED description: |- Distinguishes admin-initiated invitations from user-initiated access requests. Both share the same `user_invitations` row shape and accept/revoke flow. - INVITATION_DIRECTION_UNSPECIFIED: Unspecified — treated as INVITE for backward compatibility. - INVITATION_DIRECTION_INVITE: Admin invites a user to join an org or workspace. (Default; pre-existing behavior.) - INVITATION_DIRECTION_REQUEST: User requests access to an org or workspace they can't currently reach (powers the No Access page's "Request access" button). v1InvitationRole: type: object properties: id: type: string title: |- Identifies the role. For a built-in template this is the same bare id as in `UserInvitation.role_template_ids` (e.g. "agora.viewer"). For a workspace custom role it is the resource name invites accept: 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 resolved, in which case clients should fall back to formatting `id`. description: A role granted by an invitation, as listed on `UserInvitation`. v1InvitationStatus: type: string enum: - INVITATION_STATUS_UNSPECIFIED - INVITATION_STATUS_SENT - INVITATION_STATUS_ACCEPTED - INVITATION_STATUS_REVOKED - INVITATION_STATUS_DECLINED default: INVITATION_STATUS_UNSPECIFIED description: |- Lifecycle status of an invitation, surfacing the Postgres enum on `user_invitations.invitation_status`. - INVITATION_STATUS_UNSPECIFIED: Unspecified — older clients that don't populate the field on the wire. - INVITATION_STATUS_SENT: Invitation has been created but the invitee has not yet acted on it. - INVITATION_STATUS_ACCEPTED: Invitee accepted; corresponding role assignments have been created. - INVITATION_STATUS_REVOKED: Inviter revoked the invitation before the invitee acted. - INVITATION_STATUS_DECLINED: Invitee declined the invitation. v1RolePermission: type: object properties: permission: type: string title: |- The permission this describes, matching an entry in `Role.permissions`. Format: "{action}:{resource_path}" (e.g., "GET:/api/v1/me") display_name: type: string description: |- Human-readable name of the permission (e.g., "me:read"). Mirrors 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. Carries only the human-readable name and description: the action and resource path are already encoded in the `Role.permissions` string this joins to, so repeating them would double the payload of the field it describes for no gain. v1RunContentCoverage: type: object properties: file_count: type: integer format: int32 description: The number of files found in the run. readOnly: true indexed_file_count: type: integer format: int32 description: The number of files whose text is searchable. readOnly: true partially_indexed_file_count: type: integer format: int32 description: |- The number of indexed files that are only partly searchable, because their text was cut off at a size limit or some of their pages have no text layer. These files are also counted in indexed_file_count, so this is never larger. readOnly: true pending_file_count: type: integer format: int32 description: |- The number of files not indexed yet: waiting, being read, or due for a retry after a temporary error. readOnly: true skipped_file_counts: type: array items: $ref: "#/components/schemas/v1SkippedFileCount" description: |- The files that will not be indexed, counted by reason. Holds one entry for each reason that applies to at least one file, in no particular order. readOnly: true description: |- RunContentCoverage counts a run's files by whether the ListRuns search filter term can match the text inside them. The files counted are those in the run's inputs, outputs and trigger payload, the files its steps used as recorded in the Run log, and text values offloaded to object storage. Text the steps produced is not a file and is not counted. A file is counted once however many places it appears in, and in exactly one of indexed_file_count, pending_file_count and skipped_file_counts, so file_count is their sum. The counts cover the files found so far: a run that is still executing, or whose Run log has not been read yet, can gain files later. v1RunContentMatch: type: object properties: file_matches: type: array items: $ref: "#/components/schemas/v1FileContentMatch" description: |- The files whose text contains a search term. A file can have more than one entry, for example an input that a step also read. Holds at most a server-chosen number of entries, and file_match_count says how many there are in all; the limit is an operational choice and may change, so do not treat it as part of the contract. readOnly: true file_match_count: type: integer format: int32 description: |- The number of entries file_matches would hold without its limit, so a client can show how many were left out. readOnly: true description: |- Where a run matched the ListRuns search term inside the text of its files. Names files and locations only, never the matched text. v1SkippedFileCount: type: object properties: reason: $ref: "#/components/schemas/v1ContentSkipReason" file_count: type: integer format: int32 description: The number of files skipped for this reason. readOnly: true description: The number of a run's files that content search skipped for one reason. v1UserWorkspaceMembership: type: object properties: workspace: type: string title: |- Resource name of the workspace this membership refers to. Format: organizations/{organization}/workspaces/{workspace} your_roles: type: array items: $ref: "#/components/schemas/v1RoleBasicInfo" description: |- The current user's role assignments scoped to this workspace. Empty 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 `user_roles.created_at` for any of their roles in this workspace. Unset if the user has no direct workspace-level role assignment. description: |- Per-workspace membership context for the current user, returned alongside `Workspace` in `CurrentUserOrganizationWorkspacesResponse.memberships`. required: - workspace v1ValueNoneType: type: object title: Represents a none value type that can hold no value 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). - WEEK_START_SUNDAY: Week starts on Sunday. - WEEK_START_MONDAY: Week starts on Monday. title: First day of the week, surfaced via GeneralPreferences.week_start. 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. Deliberately kept in its own file with no imports. `WorkspaceType` is needed by both `types.proto` (on `Workspace`) and `rbac.proto` (on `RoleTemplate`), and `types.proto` already imports `rbac.proto` for `RoleScope` — so defining it in either of those files makes the other's import cyclic. - WORKSPACE_TYPE_UNSPECIFIED: Not set. Not a workspace category in its own right: a workspace created without an explicit type is treated as WORKSPACE_TYPE_REGULAR, and this value is not a valid member of `RoleTemplate.workspace_types`. - WORKSPACE_TYPE_FINANCE: Finance workspace. - WORKSPACE_TYPE_REGULAR: Regular (general-purpose, automation-oriented) workspace — the default for workspaces created without an explicit type. Numbered after FINANCE only because renumbering an existing value is a wire break; REGULAR is the baseline kind, not a later addition.