Understanding the ai.edgelq.com service APIv1, in proto package ntt.ai.v1.

Service ai.edgelq.com in version v1, proto package ntt.ai.v1

Here is the list of resources supported in AI service APIv1:

CapabilityTemplate Resource

CapabilityTemplate Resource

Name patterns:

  • capabilityTemplates/{capability_template}
  • projects/{project}/capabilityTemplates/{capability_template}

Parent resources:

This section covers the methods and messages to interact with CapabilityTemplate resource.

CapabilityTemplate Methods

Here is the list of CapabilityTemplate resource methods:

GetCapabilityTemplate Method

GetCapabilityTemplate

rpc GetCapabilityTemplate(GetCapabilityTemplateRequest) returns (CapabilityTemplate)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/capabilityTemplates.get

The equivalent REST API is:

GET /v1/{name=capabilityTemplates/*} 

GET /v1/{name=projects/*/capabilityTemplates/*}

BatchGetCapabilityTemplates Method

BatchGetCapabilityTemplates

rpc BatchGetCapabilityTemplates(BatchGetCapabilityTemplatesRequest) returns (BatchGetCapabilityTemplatesResponse)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/capabilityTemplates.batchGet

The equivalent REST API is:

GET /v1/capabilityTemplates:batchGet

ListCapabilityTemplates Method

ListCapabilityTemplates

rpc ListCapabilityTemplates(ListCapabilityTemplatesRequest) returns (ListCapabilityTemplatesResponse)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/capabilityTemplates.list

The equivalent REST API is:

GET /v1/capabilityTemplates 

GET /v1/{parent=projects/*}/capabilityTemplates

WatchCapabilityTemplate Method

WatchCapabilityTemplate

rpc WatchCapabilityTemplate(WatchCapabilityTemplateRequest) returns (WatchCapabilityTemplateResponse)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/capabilityTemplates.watch

The equivalent REST API is:

POST /v1/{name=capabilityTemplates/*}:watch 

POST /v1/{name=projects/*/capabilityTemplates/*}:watch

WatchCapabilityTemplates Method

WatchCapabilityTemplates

rpc WatchCapabilityTemplates(WatchCapabilityTemplatesRequest) returns (WatchCapabilityTemplatesResponse)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/capabilityTemplates.watch

The equivalent REST API is:

POST /v1/capabilityTemplates:watch 

POST /v1/{parent=projects/*}/capabilityTemplates:watch

CreateCapabilityTemplate Method

CreateCapabilityTemplate

rpc CreateCapabilityTemplate(CreateCapabilityTemplateRequest) returns (CapabilityTemplate)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/capabilityTemplates.create

The equivalent REST API is:

POST /v1/capabilityTemplates (BODY: capability_template)

POST /v1/{parent=projects/*}/capabilityTemplates

UpdateCapabilityTemplate Method

UpdateCapabilityTemplate

rpc UpdateCapabilityTemplate(UpdateCapabilityTemplateRequest) returns (CapabilityTemplate)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/capabilityTemplates.update

The equivalent REST API is:

PUT /v1/{capability_template.name=capabilityTemplates/*} (BODY: capability_template)

PUT /v1/{capability_template.name=projects/*/capabilityTemplates/*}

DeleteCapabilityTemplate Method

DeleteCapabilityTemplate

rpc DeleteCapabilityTemplate(DeleteCapabilityTemplateRequest) returns (Empty)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/capabilityTemplates.delete

The equivalent REST API is:

DELETE /v1/{name=capabilityTemplates/*} 

DELETE /v1/{name=projects/*/capabilityTemplates/*}

PreviewTemplateTools Method

PreviewTemplateTools

rpc PreviewTemplateTools(PreviewTemplateToolsRequest) returns (PreviewTemplateToolsResponse)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/capabilityTemplates.previewTools

The equivalent REST API is:

POST /v1/{name=capabilityTemplates/*}:previewTools 

POST /v1/{name=projects/*/capabilityTemplates/*}:previewTools

CapabilityTemplate Messages

Here is the list of CapabilityTemplate resource messages:

CapabilityTemplate Message

Name Type Description
name string (name of CapabilityTemplate) Name of CapabilityTemplate When creating a new instance, this field is optional and if not provided, it will be generated automatically. Last ID segment must conform to the following regex: [a-z][a-z0-9\-]{0,28}[a-z0-9]
metadata Meta Metadata is an object with information like create, update and delete time (for async deleted resources), has user labels/annotations, sharding information, multi-region syncing information and may have non-schema owners (useful for taking ownership of resources belonging to lower level services by higher ones).
description string Human-readable description
connectors repeated string (reference to Connector) Connectors to include
rag_config RAGConfig RAG configuration (optional)
display_name string Human-readable display name
reasoning ReasoningConfig Reasoning/thinking configuration and limits
max_output_tokens int32 Maximum output tokens (overrides ChatModel’s default if set)
system_prompt string When set, this prompt will be used instead of a default system prompt.
system_prompt_append PromptAppendTemplate Optional: a templated append that will be rendered and appended to the base system prompt (or the user input for client provided variables).
disable_input_token_cache bool When true, disables Anthropic prompt caching (default: caching enabled)
allowed_models repeated string (reference to ChatModel) Allowed chat models for this template (optional) If empty, any model can be used with this template If specified, only models in this list can be used with this template This allows organizations to control which models are used for specific use cases, capabilities, or compliance requirements
tool_safety ToolSafetyConfig Tool safety configuration for loop detection (optional)
default_model string (name of ChatModel) Default model for this template (optional)
user_prompt_templates repeated UserPromptTemplate User prompt template library for this capability Client-side only: server stores, client renders and executes

GetCapabilityTemplateRequest Message

A request message of the GetCapabilityTemplate method.

Name Type Description
name string (name of CapabilityTemplate) Name of ntt.ai.v1.CapabilityTemplate
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetCapabilityTemplatesRequest Message

A request message of the BatchGetCapabilityTemplates method.

Name Type Description
names repeated string (name of CapabilityTemplate) Names of CapabilityTemplates
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetCapabilityTemplatesResponse Message

A response message of the BatchGetCapabilityTemplates method.

Name Type Description
capability_templates repeated CapabilityTemplate found CapabilityTemplates
missing repeated string (name of CapabilityTemplate) list of not found CapabilityTemplates

ListCapabilityTemplatesRequest Message

A request message of the ListCapabilityTemplates method.

Name Type Description
parent string (parent name of CapabilityTemplate) Parent name of ntt.ai.v1.CapabilityTemplate
page_size int32 Requested page size. Server may return fewer CapabilityTemplates than requested. If unspecified, server will pick an appropriate default.
page_token string (cursor of CapabilityTemplate) A token identifying a page of results the server should return. Typically, this is the value of ListCapabilityTemplatesResponse.next_page_token.
order_by string (orderBy of CapabilityTemplate) Order By - https://cloud.google.com/apis/design/design_patterns#list_pagination list of field path with order directive, either ‘asc’ or ‘desc’. If direction is not provided, ‘asc’ is assumed. e.g. “state.nested_field asc, state.something.else desc, theme”
filter string (filter of CapabilityTemplate) Filter - filter results by field criteria. Simplified SQL-like syntax with following operators: <=, >=, =, !=, <, >, LIKE, CONTAINS (aliases CONTAIN, HAS, HAVE), IN, IS [NOT] NULL
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask
include_paging_info bool Indicates if list response should contain total count and offset (fields current_offset and total_results_count).

ListCapabilityTemplatesResponse Message

A response message of the ListCapabilityTemplates method.

Name Type Description
capability_templates repeated CapabilityTemplate The list of CapabilityTemplates
prev_page_token string (cursor of CapabilityTemplate) A token to retrieve previous page of results. Pass this value in the ListCapabilityTemplatesRequest.page_token.
next_page_token string (cursor of CapabilityTemplate) A token to retrieve next page of results. Pass this value in the ListCapabilityTemplatesRequest.page_token.
current_offset int32 Current offset from the first page or 0 if no page tokens were given, paging info was not requested or there was an error while trying to get it). Page index can be computed from offset and limit provided in a request.
total_results_count int32 Number of total CapabilityTemplates across all pages or 0, if there are no items, paging info was not requested or there was an error while trying to get it.

WatchCapabilityTemplateRequest Message

A request message of the WatchCapabilityTemplate method.

Name Type Description
name string (name of CapabilityTemplate) Name of ntt.ai.v1.CapabilityTemplate
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

WatchCapabilityTemplateResponse Message

A response message of the WatchCapabilityTemplate method.

Name Type Description
change CapabilityTemplateChange

WatchCapabilityTemplatesRequest Message

A request message of the WatchCapabilityTemplates method.

Name Type Description
type WatchType Type of a watch. Identifies how server stream data to a client, which fields in a request are allowed and which fields in response are relevant.
parent string (parent name of CapabilityTemplate) Parent name of ntt.ai.v1.CapabilityTemplate
page_size int32 Requested page size. Server may return fewer CapabilityTemplates than requested. If unspecified, server will pick an appropriate default. Can be populated only for stateful watch type.
page_token string (cursor of CapabilityTemplate) A token identifying a page of results the server should return. Can be populated only for stateful watch type.
order_by string (orderBy of CapabilityTemplate) Order By - https://cloud.google.com/apis/design/design_patterns#list_pagination Can be populated only for stateful watch type.
resume_token string A token identifying watch resume point from previous session. Can be populated only for stateless watch type.
starting_time .google.protobuf.Timestamp Point in the time from which we want to start getting updates. This field can be populated only for stateless watch type and if resume token is not known yet. If specified, initial snapshot will NOT be provided. It is assumed client can obtain it using separate means. Watch responses will contain resume tokens which should be used to resume broken connection.
filter string (filter of CapabilityTemplate) Filter - filter results by field criteria. Simplified SQL-like syntax with following operators: <=, >=, =, !=, <, >, LIKE, CONTAINS (aliases CONTAIN, HAS, HAVE), IN, IS [NOT] NULL
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view Changes to CapabilityTemplate that don’t affect any of masked fields won’t be sent back.
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask Changes to CapabilityTemplate that don’t affect any of masked fields won’t be sent back.
max_chunk_size int32 Maximum amount of changes in each response message. Query result response is divided on the server side into chunks with size of a specified amount to limit memory footprint of each message. Responses will hold information whether more elements will continue for the actual change. If unspecified, server will pick an appropriate default.

WatchCapabilityTemplatesResponse Message

A response message of the WatchCapabilityTemplates method.

Name Type Description
capability_template_changes repeated CapabilityTemplateChange Changes of CapabilityTemplates
is_current bool If request specified max_chunk_size (or this limit was enforced if stateless watch has been chosen), then responses with “full changeset” will be divided into chunks. Client should keep receiving messages and, once is_current has value true, combine this recent message with all previous ones where is_current is false. If this is the first is_current in a whole watch stream, then it means that client should have, at this moment, contain snapshot of the current situation (or more accurately, snapshot of situation at the moment of request). All CapabilityTemplates will be of type Added/Current (depending on watch_type specified in the request). Further responses will be incremental - however messages may still be chunked and is_current logic still applies. is_current is always true for stateful watch if max_chunk_size was left to 0.
page_token_change WatchCapabilityTemplatesResponse.PageTokenChange When present, PageTokens used for page navigation should be updated. Present only if is_current is true (last chunk).
resume_token string Token that can be used if current connection drops and client needs to reconnect. Populated only for stateless watch type. Present only if is_current is true (last chunk).
snapshot_size int64 Server may occasionally send information how many resources should client have in its state so far (response message without any changes, but with snapshot_size field specified). If client has different value than the one sent by the server, then it should be treated by a client as an error and should reconnect. If value is smaller then 0, then client should ignore this field as unpopulated. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will be never sent together with is_current, is_soft_reset and is_hard_reset flags.
is_soft_reset bool In case of internal issue server may send response message with this flag. It indicates that client should drop all changes from recent responses where is_current is false only! If last message had is_current set to true, client should do nothing and process normally. Resume token received before is still valid. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will never be sent along with is_current, is_hard_reset or snapshot_size.
is_hard_reset bool In case of internal issue server may send response message with this flag. After receiving, client should clear whole state (drop all changes received so far) as server will send new snapshot (CapabilityTemplates will contains changes of type Current only). Any resume tokens should be discarded as well. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will never be sent along with is_current, is_soft_reset or snapshot_size.

WatchCapabilityTemplatesResponse.PageTokenChange Message

Name Type Description
prev_page_token string (cursor of CapabilityTemplate) New token to retrieve previous page of results.
next_page_token string (cursor of CapabilityTemplate) New token to retrieve next page of results.

CreateCapabilityTemplateRequest Message

A request message of the CreateCapabilityTemplate method.

Name Type Description
parent string (parent name of CapabilityTemplate) Parent name of ntt.ai.v1.CapabilityTemplate
capability_template CapabilityTemplate CapabilityTemplate resource body
response_mask CreateCapabilityTemplateRequest.ResponseMask Optional masking applied to response object to reduce message response size.

CreateCapabilityTemplateRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

Name Type Description
skip_entire_response_body bool If this flag has value true, then response will contain just empty resource without any fields populated.
body_mask .google.protobuf.FieldMask If this field is populated, then resource in response will contain only specific fields.

UpdateCapabilityTemplateRequest Message

A request message of the UpdateCapabilityTemplate method.

Name Type Description
capability_template CapabilityTemplate CapabilityTemplate resource body
update_mask .google.protobuf.FieldMask FieldMask applied to request - change will be applied only for fields in the mask
cas UpdateCapabilityTemplateRequest.CAS Conditional update applied to request if update should be executed only for specific resource state. If this field is populated, then server will fetch existing resource, compare with the one stored in the cas field (after applying field mask) and proceed with update only and only if they match. Otherwise RPC error Aborted will be returned.
allow_missing bool If set to true, and the resource is not found, a new resource will be created. In this situation, ‘field_mask’ is ignored. https://google.aip.dev/134#create-or-update
response_mask UpdateCapabilityTemplateRequest.ResponseMask reduce message response size.

UpdateCapabilityTemplateRequest.CAS Message

CAS - Compare and Swap. This object is used if user wants to make update conditional based upon previous resource version.

Name Type Description
conditional_state CapabilityTemplate Conditional desired state of a resource before update.
field_mask .google.protobuf.FieldMask Field paths from conditional state of resource server should check and compare.

UpdateCapabilityTemplateRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

Name Type Description
skip_entire_response_body bool If this flag has value true, then response will contain just empty resource without any fields populated. Field body_mask is ignored if set.
updated_fields_only bool Include all fields that were actually updated during processing. Note this may be larger than update mask if some fields were computed additionally. Name is added as well.
body_mask .google.protobuf.FieldMask If this field is populated, then resource in response will contain only specific fields. If skip_entire_response_body is true, this field is ignored.

DeleteCapabilityTemplateRequest Message

A request message of the DeleteCapabilityTemplate method.

Name Type Description
name string (name of CapabilityTemplate) Name of ntt.ai.v1.CapabilityTemplate
allow_missing bool If set to true, and the resource is not found, method will be successful and will not return NotFound error.

PreviewTemplateToolsRequest Message

A request message of the PreviewTemplateTools method.

Name Type Description
name string (name of CapabilityTemplate) Name of ntt.ai.v1.CapabilityTemplate
client_tools repeated ToolDefinition Optional: Client tools to include in the preview

PreviewTemplateToolsResponse Message

A response message of the PreviewTemplateTools method.

Name Type Description
tools repeated ToolDefinition All tools that would be available with this template (after applying allow/deny patterns and including client tools)
errors repeated string Any errors encountered during tool discovery

ChatModel Resource

ChatModel Resource represents deployment of an AI chat model.

Name patterns:

  • chatModels/{chat_model}
  • projects/{project}/chatModels/{chat_model}

Parent resources:

This section covers the methods and messages to interact with ChatModel resource.

ChatModel Methods

Here is the list of ChatModel resource methods:

GetChatModel Method

GetChatModel

rpc GetChatModel(GetChatModelRequest) returns (ChatModel)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/chatModels.get

The equivalent REST API is:

GET /v1/{name=chatModels/*} 

GET /v1/{name=projects/*/chatModels/*}

BatchGetChatModels Method

BatchGetChatModels

rpc BatchGetChatModels(BatchGetChatModelsRequest) returns (BatchGetChatModelsResponse)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/chatModels.batchGet

The equivalent REST API is:

GET /v1/chatModels:batchGet

ListChatModels Method

ListChatModels

rpc ListChatModels(ListChatModelsRequest) returns (ListChatModelsResponse)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/chatModels.list

The equivalent REST API is:

GET /v1/chatModels 

GET /v1/{parent=projects/*}/chatModels

WatchChatModel Method

WatchChatModel

rpc WatchChatModel(WatchChatModelRequest) returns (WatchChatModelResponse)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/chatModels.watch

The equivalent REST API is:

POST /v1/{name=chatModels/*}:watch 

POST /v1/{name=projects/*/chatModels/*}:watch

WatchChatModels Method

WatchChatModels

rpc WatchChatModels(WatchChatModelsRequest) returns (WatchChatModelsResponse)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/chatModels.watch

The equivalent REST API is:

POST /v1/chatModels:watch 

POST /v1/{parent=projects/*}/chatModels:watch

CreateChatModel Method

CreateChatModel

rpc CreateChatModel(CreateChatModelRequest) returns (ChatModel)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/chatModels.create

The equivalent REST API is:

POST /v1/chatModels (BODY: chat_model)

POST /v1/{parent=projects/*}/chatModels

UpdateChatModel Method

UpdateChatModel

rpc UpdateChatModel(UpdateChatModelRequest) returns (ChatModel)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/chatModels.update

The equivalent REST API is:

PUT /v1/{chat_model.name=chatModels/*} (BODY: chat_model)

PUT /v1/{chat_model.name=projects/*/chatModels/*}

DeleteChatModel Method

DeleteChatModel

rpc DeleteChatModel(DeleteChatModelRequest) returns (Empty)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/chatModels.delete

The equivalent REST API is:

DELETE /v1/{name=chatModels/*} 

DELETE /v1/{name=projects/*/chatModels/*}

ChatModel Messages

Here is the list of ChatModel resource messages:

ChatModel Message

Name Type Description
name string (name of ChatModel) Name of ChatModel When creating a new instance, this field is optional and if not provided, it will be generated automatically. Last ID segment must conform to the following regex: [a-z][a-z0-9\-]{0,28}[a-z0-9]
metadata Meta Metadata is an object with information like create, update and delete time (for async deleted resources), has user labels/annotations, sharding information, multi-region syncing information and may have non-schema owners (useful for taking ownership of resources belonging to lower level services by higher ones).
azure_open_ai ChatModel.AzureOpenAi
openai_compatible ChatModel.OpenAICompatible
anthropic ChatModel.Anthropic
gemini ChatModel.Gemini
display_name string Human-readable display name
cost ChatModel.Cost Optional cost metadata (pricing per 1M tokens).
retired bool When true, this model is retired: hidden from ChatModel listings by default and blocked for new chats/responses. Existing conversations stay readable and can be continued by selecting a non-retired model.

ChatModel.OpenAICompatible Message

Name Type Description
api_key string (reference to Secret)
model string Model name or Azure deployment name
base_url string Optional: Custom endpoint for compatible APIs
organization string Optional: OpenAI organization ID
azure_endpoint string Optional: Azure-specific endpoint (e.g., https://myresource.openai.azure.com)
azure_api_version string Optional: Azure API version (e.g., “2024-06-01”)
max_output_tokens int32 Maximum output tokens
device string (reference to Device) Optional: route requests through proxies to an OpenAI-compatible endpoint reachable from this device.

ChatModel.Anthropic Message

Name Type Description
api_key string (reference to Secret)
model string Model name (e.g., “claude-3-opus”, “claude-3-sonnet”)
base_url string Optional: Custom endpoint
max_output_tokens int32 Maximum output tokens (must be >= 4096 for Anthropic)

ChatModel.Gemini Message

Name Type Description
api_key string (reference to Secret)
model string Model name (e.g., “gemini-pro”, “gemini-ultra”)
max_output_tokens int32 Maximum output tokens

ChatModel.AzureOpenAi Message

Name Type Description
endpoint string Azure OpenAI endpoint (e.g., https://myresource.openai.azure.com)
api_key string (reference to Secret) Azure API key
deployment_name string Azure deployment name
api_version string API version (e.g., “2024-10-21”)
max_output_tokens int32 Maximum output tokens

ChatModel.Cost Message

Cost captures pricing per 1M tokens for each billing bucket.

Name Type Description
input_per_million .google.type.Money Cost for uncached input tokens per 1M tokens.
cached_input_per_million .google.type.Money Cost for cached input tokens per 1M tokens (discounted rate).
cache_write_five_min_per_million .google.type.Money Cost for cache writes with a 5 minute TTL per 1M tokens.
cache_write_one_hour_per_million .google.type.Money Cost for cache writes with a 1 hour TTL per 1M tokens.
output_per_million .google.type.Money Cost for output tokens per 1M tokens.

GetChatModelRequest Message

A request message of the GetChatModel method.

Name Type Description
name string (name of ChatModel) Name of ntt.ai.v1.ChatModel
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetChatModelsRequest Message

A request message of the BatchGetChatModels method.

Name Type Description
names repeated string (name of ChatModel) Names of ChatModels
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetChatModelsResponse Message

A response message of the BatchGetChatModels method.

Name Type Description
chat_models repeated ChatModel found ChatModels
missing repeated string (name of ChatModel) list of not found ChatModels

ListChatModelsRequest Message

A request message of the ListChatModels method.

Name Type Description
parent string (parent name of ChatModel) Parent name of ntt.ai.v1.ChatModel
page_size int32 Requested page size. Server may return fewer ChatModels than requested. If unspecified, server will pick an appropriate default.
page_token string (cursor of ChatModel) A token identifying a page of results the server should return. Typically, this is the value of ListChatModelsResponse.next_page_token.
order_by string (orderBy of ChatModel) Order By - https://cloud.google.com/apis/design/design_patterns#list_pagination list of field path with order directive, either ‘asc’ or ‘desc’. If direction is not provided, ‘asc’ is assumed. e.g. “state.nested_field asc, state.something.else desc, theme”
filter string (filter of ChatModel) Filter - filter results by field criteria. Simplified SQL-like syntax with following operators: <=, >=, =, !=, <, >, LIKE, CONTAINS (aliases CONTAIN, HAS, HAVE), IN, IS [NOT] NULL
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask
include_paging_info bool Indicates if list response should contain total count and offset (fields current_offset and total_results_count).

ListChatModelsResponse Message

A response message of the ListChatModels method.

Name Type Description
chat_models repeated ChatModel The list of ChatModels
prev_page_token string (cursor of ChatModel) A token to retrieve previous page of results. Pass this value in the ListChatModelsRequest.page_token.
next_page_token string (cursor of ChatModel) A token to retrieve next page of results. Pass this value in the ListChatModelsRequest.page_token.
current_offset int32 Current offset from the first page or 0 if no page tokens were given, paging info was not requested or there was an error while trying to get it). Page index can be computed from offset and limit provided in a request.
total_results_count int32 Number of total ChatModels across all pages or 0, if there are no items, paging info was not requested or there was an error while trying to get it.

WatchChatModelRequest Message

A request message of the WatchChatModel method.

Name Type Description
name string (name of ChatModel) Name of ntt.ai.v1.ChatModel
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

WatchChatModelResponse Message

A response message of the WatchChatModel method.

Name Type Description
change ChatModelChange

WatchChatModelsRequest Message

A request message of the WatchChatModels method.

Name Type Description
type WatchType Type of a watch. Identifies how server stream data to a client, which fields in a request are allowed and which fields in response are relevant.
parent string (parent name of ChatModel) Parent name of ntt.ai.v1.ChatModel
page_size int32 Requested page size. Server may return fewer ChatModels than requested. If unspecified, server will pick an appropriate default. Can be populated only for stateful watch type.
page_token string (cursor of ChatModel) A token identifying a page of results the server should return. Can be populated only for stateful watch type.
order_by string (orderBy of ChatModel) Order By - https://cloud.google.com/apis/design/design_patterns#list_pagination Can be populated only for stateful watch type.
resume_token string A token identifying watch resume point from previous session. Can be populated only for stateless watch type.
starting_time .google.protobuf.Timestamp Point in the time from which we want to start getting updates. This field can be populated only for stateless watch type and if resume token is not known yet. If specified, initial snapshot will NOT be provided. It is assumed client can obtain it using separate means. Watch responses will contain resume tokens which should be used to resume broken connection.
filter string (filter of ChatModel) Filter - filter results by field criteria. Simplified SQL-like syntax with following operators: <=, >=, =, !=, <, >, LIKE, CONTAINS (aliases CONTAIN, HAS, HAVE), IN, IS [NOT] NULL
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view Changes to ChatModel that don’t affect any of masked fields won’t be sent back.
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask Changes to ChatModel that don’t affect any of masked fields won’t be sent back.
max_chunk_size int32 Maximum amount of changes in each response message. Query result response is divided on the server side into chunks with size of a specified amount to limit memory footprint of each message. Responses will hold information whether more elements will continue for the actual change. If unspecified, server will pick an appropriate default.

WatchChatModelsResponse Message

A response message of the WatchChatModels method.

Name Type Description
chat_model_changes repeated ChatModelChange Changes of ChatModels
is_current bool If request specified max_chunk_size (or this limit was enforced if stateless watch has been chosen), then responses with “full changeset” will be divided into chunks. Client should keep receiving messages and, once is_current has value true, combine this recent message with all previous ones where is_current is false. If this is the first is_current in a whole watch stream, then it means that client should have, at this moment, contain snapshot of the current situation (or more accurately, snapshot of situation at the moment of request). All ChatModels will be of type Added/Current (depending on watch_type specified in the request). Further responses will be incremental - however messages may still be chunked and is_current logic still applies. is_current is always true for stateful watch if max_chunk_size was left to 0.
page_token_change WatchChatModelsResponse.PageTokenChange When present, PageTokens used for page navigation should be updated. Present only if is_current is true (last chunk).
resume_token string Token that can be used if current connection drops and client needs to reconnect. Populated only for stateless watch type. Present only if is_current is true (last chunk).
snapshot_size int64 Server may occasionally send information how many resources should client have in its state so far (response message without any changes, but with snapshot_size field specified). If client has different value than the one sent by the server, then it should be treated by a client as an error and should reconnect. If value is smaller then 0, then client should ignore this field as unpopulated. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will be never sent together with is_current, is_soft_reset and is_hard_reset flags.
is_soft_reset bool In case of internal issue server may send response message with this flag. It indicates that client should drop all changes from recent responses where is_current is false only! If last message had is_current set to true, client should do nothing and process normally. Resume token received before is still valid. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will never be sent along with is_current, is_hard_reset or snapshot_size.
is_hard_reset bool In case of internal issue server may send response message with this flag. After receiving, client should clear whole state (drop all changes received so far) as server will send new snapshot (ChatModels will contains changes of type Current only). Any resume tokens should be discarded as well. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will never be sent along with is_current, is_soft_reset or snapshot_size.

WatchChatModelsResponse.PageTokenChange Message

Name Type Description
prev_page_token string (cursor of ChatModel) New token to retrieve previous page of results.
next_page_token string (cursor of ChatModel) New token to retrieve next page of results.

CreateChatModelRequest Message

A request message of the CreateChatModel method.

Name Type Description
parent string (parent name of ChatModel) Parent name of ntt.ai.v1.ChatModel
chat_model ChatModel ChatModel resource body
response_mask CreateChatModelRequest.ResponseMask Optional masking applied to response object to reduce message response size.

CreateChatModelRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

Name Type Description
skip_entire_response_body bool If this flag has value true, then response will contain just empty resource without any fields populated.
body_mask .google.protobuf.FieldMask If this field is populated, then resource in response will contain only specific fields.

UpdateChatModelRequest Message

A request message of the UpdateChatModel method.

Name Type Description
chat_model ChatModel ChatModel resource body
update_mask .google.protobuf.FieldMask FieldMask applied to request - change will be applied only for fields in the mask
cas UpdateChatModelRequest.CAS Conditional update applied to request if update should be executed only for specific resource state. If this field is populated, then server will fetch existing resource, compare with the one stored in the cas field (after applying field mask) and proceed with update only and only if they match. Otherwise RPC error Aborted will be returned.
allow_missing bool If set to true, and the resource is not found, a new resource will be created. In this situation, ‘field_mask’ is ignored. https://google.aip.dev/134#create-or-update
response_mask UpdateChatModelRequest.ResponseMask reduce message response size.

UpdateChatModelRequest.CAS Message

CAS - Compare and Swap. This object is used if user wants to make update conditional based upon previous resource version.

Name Type Description
conditional_state ChatModel Conditional desired state of a resource before update.
field_mask .google.protobuf.FieldMask Field paths from conditional state of resource server should check and compare.

UpdateChatModelRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

Name Type Description
skip_entire_response_body bool If this flag has value true, then response will contain just empty resource without any fields populated. Field body_mask is ignored if set.
updated_fields_only bool Include all fields that were actually updated during processing. Note this may be larger than update mask if some fields were computed additionally. Name is added as well.
body_mask .google.protobuf.FieldMask If this field is populated, then resource in response will contain only specific fields. If skip_entire_response_body is true, this field is ignored.

DeleteChatModelRequest Message

A request message of the DeleteChatModel method.

Name Type Description
name string (name of ChatModel) Name of ntt.ai.v1.ChatModel
allow_missing bool If set to true, and the resource is not found, method will be successful and will not return NotFound error.

Connector Resource

Connector Resource

Name patterns:

  • connectors/{connector}
  • projects/{project}/connectors/{connector}

Parent resources:

This section covers the methods and messages to interact with Connector resource.

Connector Methods

Here is the list of Connector resource methods:

GetConnector Method

GetConnector

rpc GetConnector(GetConnectorRequest) returns (Connector)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/connectors.get

The equivalent REST API is:

GET /v1/{name=connectors/*} 

GET /v1/{name=projects/*/connectors/*}

BatchGetConnectors Method

BatchGetConnectors

rpc BatchGetConnectors(BatchGetConnectorsRequest) returns (BatchGetConnectorsResponse)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/connectors.batchGet

The equivalent REST API is:

GET /v1/connectors:batchGet

ListConnectors Method

ListConnectors

rpc ListConnectors(ListConnectorsRequest) returns (ListConnectorsResponse)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/connectors.list

The equivalent REST API is:

GET /v1/connectors 

GET /v1/{parent=projects/*}/connectors

WatchConnector Method

WatchConnector

rpc WatchConnector(WatchConnectorRequest) returns (WatchConnectorResponse)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/connectors.watch

The equivalent REST API is:

POST /v1/{name=connectors/*}:watch 

POST /v1/{name=projects/*/connectors/*}:watch

WatchConnectors Method

WatchConnectors

rpc WatchConnectors(WatchConnectorsRequest) returns (WatchConnectorsResponse)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/connectors.watch

The equivalent REST API is:

POST /v1/connectors:watch 

POST /v1/{parent=projects/*}/connectors:watch

CreateConnector Method

CreateConnector

rpc CreateConnector(CreateConnectorRequest) returns (Connector)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/connectors.create

The equivalent REST API is:

POST /v1/connectors (BODY: connector)

POST /v1/{parent=projects/*}/connectors

UpdateConnector Method

UpdateConnector

rpc UpdateConnector(UpdateConnectorRequest) returns (Connector)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/connectors.update

The equivalent REST API is:

PUT /v1/{connector.name=connectors/*} (BODY: connector)

PUT /v1/{connector.name=projects/*/connectors/*}

DeleteConnector Method

DeleteConnector

rpc DeleteConnector(DeleteConnectorRequest) returns (Empty)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/connectors.delete

The equivalent REST API is:

DELETE /v1/{name=connectors/*} 

DELETE /v1/{name=projects/*/connectors/*}

ConnectOauth Method

ConnectOauth

rpc ConnectOauth(ConnectOauthRequest) returns (ConnectOauthResponse)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/connectors.connectOauth

The equivalent REST API is:

POST /v1/{name=connectors/*}:connectOauth 

POST /v1/{name=projects/*/connectors/*}:connectOauth

Connector Messages

Here is the list of Connector resource messages:

Connector Message

Name Type Description
name string (name of Connector) Name of Connector When creating a new instance, this field is optional and if not provided, it will be generated automatically. Last ID segment must conform to the following regex: [a-z][a-z0-9\-]{0,28}[a-z0-9]
metadata Meta Metadata is an object with information like create, update and delete time (for async deleted resources), has user labels/annotations, sharding information, multi-region syncing information and may have non-schema owners (useful for taking ownership of resources belonging to lower level services by higher ones).
display_name string Human-readable display name
description string Human-readable description
type Connector.Type
mcp_config MCPConfig MCP connection configuration
connect_timeout .google.protobuf.Duration Connection timeout
request_timeout .google.protobuf.Duration Request timeout
oauth_config OAuthConfig Effective OAuth configuration (static or auto-populated).

GetConnectorRequest Message

A request message of the GetConnector method.

Name Type Description
name string (name of Connector) Name of ntt.ai.v1.Connector
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetConnectorsRequest Message

A request message of the BatchGetConnectors method.

Name Type Description
names repeated string (name of Connector) Names of Connectors
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetConnectorsResponse Message

A response message of the BatchGetConnectors method.

Name Type Description
connectors repeated Connector found Connectors
missing repeated string (name of Connector) list of not found Connectors

ListConnectorsRequest Message

A request message of the ListConnectors method.

Name Type Description
parent string (parent name of Connector) Parent name of ntt.ai.v1.Connector
page_size int32 Requested page size. Server may return fewer Connectors than requested. If unspecified, server will pick an appropriate default.
page_token string (cursor of Connector) A token identifying a page of results the server should return. Typically, this is the value of ListConnectorsResponse.next_page_token.
order_by string (orderBy of Connector) Order By - https://cloud.google.com/apis/design/design_patterns#list_pagination list of field path with order directive, either ‘asc’ or ‘desc’. If direction is not provided, ‘asc’ is assumed. e.g. “state.nested_field asc, state.something.else desc, theme”
filter string (filter of Connector) Filter - filter results by field criteria. Simplified SQL-like syntax with following operators: <=, >=, =, !=, <, >, LIKE, CONTAINS (aliases CONTAIN, HAS, HAVE), IN, IS [NOT] NULL
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask
include_paging_info bool Indicates if list response should contain total count and offset (fields current_offset and total_results_count).

ListConnectorsResponse Message

A response message of the ListConnectors method.

Name Type Description
connectors repeated Connector The list of Connectors
prev_page_token string (cursor of Connector) A token to retrieve previous page of results. Pass this value in the ListConnectorsRequest.page_token.
next_page_token string (cursor of Connector) A token to retrieve next page of results. Pass this value in the ListConnectorsRequest.page_token.
current_offset int32 Current offset from the first page or 0 if no page tokens were given, paging info was not requested or there was an error while trying to get it). Page index can be computed from offset and limit provided in a request.
total_results_count int32 Number of total Connectors across all pages or 0, if there are no items, paging info was not requested or there was an error while trying to get it.

WatchConnectorRequest Message

A request message of the WatchConnector method.

Name Type Description
name string (name of Connector) Name of ntt.ai.v1.Connector
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

WatchConnectorResponse Message

A response message of the WatchConnector method.

Name Type Description
change ConnectorChange

WatchConnectorsRequest Message

A request message of the WatchConnectors method.

Name Type Description
type WatchType Type of a watch. Identifies how server stream data to a client, which fields in a request are allowed and which fields in response are relevant.
parent string (parent name of Connector) Parent name of ntt.ai.v1.Connector
page_size int32 Requested page size. Server may return fewer Connectors than requested. If unspecified, server will pick an appropriate default. Can be populated only for stateful watch type.
page_token string (cursor of Connector) A token identifying a page of results the server should return. Can be populated only for stateful watch type.
order_by string (orderBy of Connector) Order By - https://cloud.google.com/apis/design/design_patterns#list_pagination Can be populated only for stateful watch type.
resume_token string A token identifying watch resume point from previous session. Can be populated only for stateless watch type.
starting_time .google.protobuf.Timestamp Point in the time from which we want to start getting updates. This field can be populated only for stateless watch type and if resume token is not known yet. If specified, initial snapshot will NOT be provided. It is assumed client can obtain it using separate means. Watch responses will contain resume tokens which should be used to resume broken connection.
filter string (filter of Connector) Filter - filter results by field criteria. Simplified SQL-like syntax with following operators: <=, >=, =, !=, <, >, LIKE, CONTAINS (aliases CONTAIN, HAS, HAVE), IN, IS [NOT] NULL
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view Changes to Connector that don’t affect any of masked fields won’t be sent back.
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask Changes to Connector that don’t affect any of masked fields won’t be sent back.
max_chunk_size int32 Maximum amount of changes in each response message. Query result response is divided on the server side into chunks with size of a specified amount to limit memory footprint of each message. Responses will hold information whether more elements will continue for the actual change. If unspecified, server will pick an appropriate default.

WatchConnectorsResponse Message

A response message of the WatchConnectors method.

Name Type Description
connector_changes repeated ConnectorChange Changes of Connectors
is_current bool If request specified max_chunk_size (or this limit was enforced if stateless watch has been chosen), then responses with “full changeset” will be divided into chunks. Client should keep receiving messages and, once is_current has value true, combine this recent message with all previous ones where is_current is false. If this is the first is_current in a whole watch stream, then it means that client should have, at this moment, contain snapshot of the current situation (or more accurately, snapshot of situation at the moment of request). All Connectors will be of type Added/Current (depending on watch_type specified in the request). Further responses will be incremental - however messages may still be chunked and is_current logic still applies. is_current is always true for stateful watch if max_chunk_size was left to 0.
page_token_change WatchConnectorsResponse.PageTokenChange When present, PageTokens used for page navigation should be updated. Present only if is_current is true (last chunk).
resume_token string Token that can be used if current connection drops and client needs to reconnect. Populated only for stateless watch type. Present only if is_current is true (last chunk).
snapshot_size int64 Server may occasionally send information how many resources should client have in its state so far (response message without any changes, but with snapshot_size field specified). If client has different value than the one sent by the server, then it should be treated by a client as an error and should reconnect. If value is smaller then 0, then client should ignore this field as unpopulated. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will be never sent together with is_current, is_soft_reset and is_hard_reset flags.
is_soft_reset bool In case of internal issue server may send response message with this flag. It indicates that client should drop all changes from recent responses where is_current is false only! If last message had is_current set to true, client should do nothing and process normally. Resume token received before is still valid. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will never be sent along with is_current, is_hard_reset or snapshot_size.
is_hard_reset bool In case of internal issue server may send response message with this flag. After receiving, client should clear whole state (drop all changes received so far) as server will send new snapshot (Connectors will contains changes of type Current only). Any resume tokens should be discarded as well. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will never be sent along with is_current, is_soft_reset or snapshot_size.

WatchConnectorsResponse.PageTokenChange Message

Name Type Description
prev_page_token string (cursor of Connector) New token to retrieve previous page of results.
next_page_token string (cursor of Connector) New token to retrieve next page of results.

CreateConnectorRequest Message

A request message of the CreateConnector method.

Name Type Description
parent string (parent name of Connector) Parent name of ntt.ai.v1.Connector
connector Connector Connector resource body
response_mask CreateConnectorRequest.ResponseMask Optional masking applied to response object to reduce message response size.

CreateConnectorRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

Name Type Description
skip_entire_response_body bool If this flag has value true, then response will contain just empty resource without any fields populated.
body_mask .google.protobuf.FieldMask If this field is populated, then resource in response will contain only specific fields.

UpdateConnectorRequest Message

A request message of the UpdateConnector method.

Name Type Description
connector Connector Connector resource body
update_mask .google.protobuf.FieldMask FieldMask applied to request - change will be applied only for fields in the mask
cas UpdateConnectorRequest.CAS Conditional update applied to request if update should be executed only for specific resource state. If this field is populated, then server will fetch existing resource, compare with the one stored in the cas field (after applying field mask) and proceed with update only and only if they match. Otherwise RPC error Aborted will be returned.
allow_missing bool If set to true, and the resource is not found, a new resource will be created. In this situation, ‘field_mask’ is ignored. https://google.aip.dev/134#create-or-update
response_mask UpdateConnectorRequest.ResponseMask reduce message response size.

UpdateConnectorRequest.CAS Message

CAS - Compare and Swap. This object is used if user wants to make update conditional based upon previous resource version.

Name Type Description
conditional_state Connector Conditional desired state of a resource before update.
field_mask .google.protobuf.FieldMask Field paths from conditional state of resource server should check and compare.

UpdateConnectorRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

Name Type Description
skip_entire_response_body bool If this flag has value true, then response will contain just empty resource without any fields populated. Field body_mask is ignored if set.
updated_fields_only bool Include all fields that were actually updated during processing. Note this may be larger than update mask if some fields were computed additionally. Name is added as well.
body_mask .google.protobuf.FieldMask If this field is populated, then resource in response will contain only specific fields. If skip_entire_response_body is true, this field is ignored.

DeleteConnectorRequest Message

A request message of the DeleteConnector method.

Name Type Description
name string (name of Connector) Name of ntt.ai.v1.Connector
allow_missing bool If set to true, and the resource is not found, method will be successful and will not return NotFound error.

ConnectOauthRequest Message

A request message of the ConnectOauth method.

Name Type Description
name string (name of Connector) Name of ntt.ai.v1.Connector the client wants to link.
start StartOauth
cancel CancelOauth
ping OauthPing

ConnectOauthResponse Message

A response message of the ConnectOauth method.

Name Type Description
redirect OauthRedirect
completion OauthCompletion
error OauthError
keep_alive OauthKeepAlive

Connector Enumerations

Here is the list of Connector resource enumerations:

Connector.Type Enumeration

Connector type

Name Description
MCP

ConnectorUserToken Resource

ConnectorUserToken Resource

Name patterns:

  • connectorUserTokens/{connector_user_token}
  • projects/{project}/connectorUserTokens/{connector_user_token}

Parent resources:

This section covers the methods and messages to interact with ConnectorUserToken resource.

ConnectorUserToken Methods

Here is the list of ConnectorUserToken resource methods:

GetConnectorUserToken Method

GetConnectorUserToken

rpc GetConnectorUserToken(GetConnectorUserTokenRequest) returns (ConnectorUserToken)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/connectorUserTokens.get

The equivalent REST API is:

GET /v1/{name=connectorUserTokens/*} 

GET /v1/{name=projects/*/connectorUserTokens/*}

BatchGetConnectorUserTokens Method

BatchGetConnectorUserTokens

rpc BatchGetConnectorUserTokens(BatchGetConnectorUserTokensRequest) returns (BatchGetConnectorUserTokensResponse)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/connectorUserTokens.batchGet

The equivalent REST API is:

GET /v1/connectorUserTokens:batchGet

ListConnectorUserTokens Method

ListConnectorUserTokens

rpc ListConnectorUserTokens(ListConnectorUserTokensRequest) returns (ListConnectorUserTokensResponse)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/connectorUserTokens.list

The equivalent REST API is:

GET /v1/connectorUserTokens 

GET /v1/{parent=projects/*}/connectorUserTokens

WatchConnectorUserToken Method

WatchConnectorUserToken

rpc WatchConnectorUserToken(WatchConnectorUserTokenRequest) returns (WatchConnectorUserTokenResponse)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/connectorUserTokens.watch

The equivalent REST API is:

POST /v1/{name=connectorUserTokens/*}:watch 

POST /v1/{name=projects/*/connectorUserTokens/*}:watch

WatchConnectorUserTokens Method

WatchConnectorUserTokens

rpc WatchConnectorUserTokens(WatchConnectorUserTokensRequest) returns (WatchConnectorUserTokensResponse)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/connectorUserTokens.watch

The equivalent REST API is:

POST /v1/connectorUserTokens:watch 

POST /v1/{parent=projects/*}/connectorUserTokens:watch

CreateConnectorUserToken Method

CreateConnectorUserToken

rpc CreateConnectorUserToken(CreateConnectorUserTokenRequest) returns (ConnectorUserToken)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/connectorUserTokens.create

The equivalent REST API is:

POST /v1/connectorUserTokens (BODY: connector_user_token)

POST /v1/{parent=projects/*}/connectorUserTokens

UpdateConnectorUserToken Method

UpdateConnectorUserToken

rpc UpdateConnectorUserToken(UpdateConnectorUserTokenRequest) returns (ConnectorUserToken)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/connectorUserTokens.update

The equivalent REST API is:

PUT /v1/{connector_user_token.name=connectorUserTokens/*} (BODY: connector_user_token)

PUT /v1/{connector_user_token.name=projects/*/connectorUserTokens/*}

DeleteConnectorUserToken Method

DeleteConnectorUserToken

rpc DeleteConnectorUserToken(DeleteConnectorUserTokenRequest) returns (Empty)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/connectorUserTokens.delete

The equivalent REST API is:

DELETE /v1/{name=connectorUserTokens/*} 

DELETE /v1/{name=projects/*/connectorUserTokens/*}

ConnectorUserToken Messages

Here is the list of ConnectorUserToken resource messages:

ConnectorUserToken Message

Name Type Description
name string (name of ConnectorUserToken) Name of ConnectorUserToken When creating a new instance, this field is optional and if not provided, it will be generated automatically. Last ID segment must conform to the following regex: [a-z][a-z0-9\-]{0,28}[a-z0-9]
metadata Meta Metadata is an object with information like create, update and delete time (for async deleted resources), has user labels/annotations, sharding information, multi-region syncing information and may have non-schema owners (useful for taking ownership of resources belonging to lower level services by higher ones).
connector string (name of Connector) Connector resource this token authorizes against.
owner_email string IAM user email that established this token.
provider_subject string Provider specific identifier for the linked account (e.g. subject claim).
provider_display_name string Provider supplied display name for the linked identity.
provider_avatar_url string Provider supplied avatar URL for the linked identity.
granted_scopes repeated string OAuth scopes that were granted for this token.
access_token_expires_at .google.protobuf.Timestamp Expiration (if any) for the current access token.
refresh_token_expires_at .google.protobuf.Timestamp Expiration (if any) for the refresh token.
last_refresh_time .google.protobuf.Timestamp Last time the backend refreshed token material.
revoked bool Indicates whether this token has been revoked server-side.
revoked_time .google.protobuf.Timestamp When the token was revoked server-side.
revocation_reason string Optional human readable reason for revocation.
consent_obtained bool True once the user has completed any configured downstream consent flow for this connector (for example, granting access to additional provider resources such as Azure Data Explorer). This allows the backend to distinguish between initial connector login and subsequent provider-level consent requirements.
secret ConnectorUserTokenSecret Encrypted token material, only accepted from the server-side control plane.

GetConnectorUserTokenRequest Message

A request message of the GetConnectorUserToken method.

Name Type Description
name string (name of ConnectorUserToken) Name of ntt.ai.v1.ConnectorUserToken
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetConnectorUserTokensRequest Message

A request message of the BatchGetConnectorUserTokens method.

Name Type Description
names repeated string (name of ConnectorUserToken) Names of ConnectorUserTokens
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetConnectorUserTokensResponse Message

A response message of the BatchGetConnectorUserTokens method.

Name Type Description
connector_user_tokens repeated ConnectorUserToken found ConnectorUserTokens
missing repeated string (name of ConnectorUserToken) list of not found ConnectorUserTokens

ListConnectorUserTokensRequest Message

A request message of the ListConnectorUserTokens method.

Name Type Description
parent string (parent name of ConnectorUserToken) Parent name of ntt.ai.v1.ConnectorUserToken
page_size int32 Requested page size. Server may return fewer ConnectorUserTokens than requested. If unspecified, server will pick an appropriate default.
page_token string (cursor of ConnectorUserToken) A token identifying a page of results the server should return. Typically, this is the value of ListConnectorUserTokensResponse.next_page_token.
order_by string (orderBy of ConnectorUserToken) Order By - https://cloud.google.com/apis/design/design_patterns#list_pagination list of field path with order directive, either ‘asc’ or ‘desc’. If direction is not provided, ‘asc’ is assumed. e.g. “state.nested_field asc, state.something.else desc, theme”
filter string (filter of ConnectorUserToken) Filter - filter results by field criteria. Simplified SQL-like syntax with following operators: <=, >=, =, !=, <, >, LIKE, CONTAINS (aliases CONTAIN, HAS, HAVE), IN, IS [NOT] NULL
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask
include_paging_info bool Indicates if list response should contain total count and offset (fields current_offset and total_results_count).

ListConnectorUserTokensResponse Message

A response message of the ListConnectorUserTokens method.

Name Type Description
connector_user_tokens repeated ConnectorUserToken The list of ConnectorUserTokens
prev_page_token string (cursor of ConnectorUserToken) A token to retrieve previous page of results. Pass this value in the ListConnectorUserTokensRequest.page_token.
next_page_token string (cursor of ConnectorUserToken) A token to retrieve next page of results. Pass this value in the ListConnectorUserTokensRequest.page_token.
current_offset int32 Current offset from the first page or 0 if no page tokens were given, paging info was not requested or there was an error while trying to get it). Page index can be computed from offset and limit provided in a request.
total_results_count int32 Number of total ConnectorUserTokens across all pages or 0, if there are no items, paging info was not requested or there was an error while trying to get it.

WatchConnectorUserTokenRequest Message

A request message of the WatchConnectorUserToken method.

Name Type Description
name string (name of ConnectorUserToken) Name of ntt.ai.v1.ConnectorUserToken
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

WatchConnectorUserTokenResponse Message

A response message of the WatchConnectorUserToken method.

Name Type Description
change ConnectorUserTokenChange

WatchConnectorUserTokensRequest Message

A request message of the WatchConnectorUserTokens method.

Name Type Description
type WatchType Type of a watch. Identifies how server stream data to a client, which fields in a request are allowed and which fields in response are relevant.
parent string (parent name of ConnectorUserToken) Parent name of ntt.ai.v1.ConnectorUserToken
page_size int32 Requested page size. Server may return fewer ConnectorUserTokens than requested. If unspecified, server will pick an appropriate default. Can be populated only for stateful watch type.
page_token string (cursor of ConnectorUserToken) A token identifying a page of results the server should return. Can be populated only for stateful watch type.
order_by string (orderBy of ConnectorUserToken) Order By - https://cloud.google.com/apis/design/design_patterns#list_pagination Can be populated only for stateful watch type.
resume_token string A token identifying watch resume point from previous session. Can be populated only for stateless watch type.
starting_time .google.protobuf.Timestamp Point in the time from which we want to start getting updates. This field can be populated only for stateless watch type and if resume token is not known yet. If specified, initial snapshot will NOT be provided. It is assumed client can obtain it using separate means. Watch responses will contain resume tokens which should be used to resume broken connection.
filter string (filter of ConnectorUserToken) Filter - filter results by field criteria. Simplified SQL-like syntax with following operators: <=, >=, =, !=, <, >, LIKE, CONTAINS (aliases CONTAIN, HAS, HAVE), IN, IS [NOT] NULL
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view Changes to ConnectorUserToken that don’t affect any of masked fields won’t be sent back.
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask Changes to ConnectorUserToken that don’t affect any of masked fields won’t be sent back.
max_chunk_size int32 Maximum amount of changes in each response message. Query result response is divided on the server side into chunks with size of a specified amount to limit memory footprint of each message. Responses will hold information whether more elements will continue for the actual change. If unspecified, server will pick an appropriate default.

WatchConnectorUserTokensResponse Message

A response message of the WatchConnectorUserTokens method.

Name Type Description
connector_user_token_changes repeated ConnectorUserTokenChange Changes of ConnectorUserTokens
is_current bool If request specified max_chunk_size (or this limit was enforced if stateless watch has been chosen), then responses with “full changeset” will be divided into chunks. Client should keep receiving messages and, once is_current has value true, combine this recent message with all previous ones where is_current is false. If this is the first is_current in a whole watch stream, then it means that client should have, at this moment, contain snapshot of the current situation (or more accurately, snapshot of situation at the moment of request). All ConnectorUserTokens will be of type Added/Current (depending on watch_type specified in the request). Further responses will be incremental - however messages may still be chunked and is_current logic still applies. is_current is always true for stateful watch if max_chunk_size was left to 0.
page_token_change WatchConnectorUserTokensResponse.PageTokenChange When present, PageTokens used for page navigation should be updated. Present only if is_current is true (last chunk).
resume_token string Token that can be used if current connection drops and client needs to reconnect. Populated only for stateless watch type. Present only if is_current is true (last chunk).
snapshot_size int64 Server may occasionally send information how many resources should client have in its state so far (response message without any changes, but with snapshot_size field specified). If client has different value than the one sent by the server, then it should be treated by a client as an error and should reconnect. If value is smaller then 0, then client should ignore this field as unpopulated. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will be never sent together with is_current, is_soft_reset and is_hard_reset flags.
is_soft_reset bool In case of internal issue server may send response message with this flag. It indicates that client should drop all changes from recent responses where is_current is false only! If last message had is_current set to true, client should do nothing and process normally. Resume token received before is still valid. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will never be sent along with is_current, is_hard_reset or snapshot_size.
is_hard_reset bool In case of internal issue server may send response message with this flag. After receiving, client should clear whole state (drop all changes received so far) as server will send new snapshot (ConnectorUserTokens will contains changes of type Current only). Any resume tokens should be discarded as well. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will never be sent along with is_current, is_soft_reset or snapshot_size.

WatchConnectorUserTokensResponse.PageTokenChange Message

Name Type Description
prev_page_token string (cursor of ConnectorUserToken) New token to retrieve previous page of results.
next_page_token string (cursor of ConnectorUserToken) New token to retrieve next page of results.

CreateConnectorUserTokenRequest Message

A request message of the CreateConnectorUserToken method.

Name Type Description
parent string (parent name of ConnectorUserToken) Parent name of ntt.ai.v1.ConnectorUserToken
connector_user_token ConnectorUserToken ConnectorUserToken resource body
response_mask CreateConnectorUserTokenRequest.ResponseMask Optional masking applied to response object to reduce message response size.

CreateConnectorUserTokenRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

Name Type Description
skip_entire_response_body bool If this flag has value true, then response will contain just empty resource without any fields populated.
body_mask .google.protobuf.FieldMask If this field is populated, then resource in response will contain only specific fields.

UpdateConnectorUserTokenRequest Message

A request message of the UpdateConnectorUserToken method.

Name Type Description
connector_user_token ConnectorUserToken ConnectorUserToken resource body
update_mask .google.protobuf.FieldMask FieldMask applied to request - change will be applied only for fields in the mask
cas UpdateConnectorUserTokenRequest.CAS Conditional update applied to request if update should be executed only for specific resource state. If this field is populated, then server will fetch existing resource, compare with the one stored in the cas field (after applying field mask) and proceed with update only and only if they match. Otherwise RPC error Aborted will be returned.
allow_missing bool If set to true, and the resource is not found, a new resource will be created. In this situation, ‘field_mask’ is ignored. https://google.aip.dev/134#create-or-update
response_mask UpdateConnectorUserTokenRequest.ResponseMask reduce message response size.

UpdateConnectorUserTokenRequest.CAS Message

CAS - Compare and Swap. This object is used if user wants to make update conditional based upon previous resource version.

Name Type Description
conditional_state ConnectorUserToken Conditional desired state of a resource before update.
field_mask .google.protobuf.FieldMask Field paths from conditional state of resource server should check and compare.

UpdateConnectorUserTokenRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

Name Type Description
skip_entire_response_body bool If this flag has value true, then response will contain just empty resource without any fields populated. Field body_mask is ignored if set.
updated_fields_only bool Include all fields that were actually updated during processing. Note this may be larger than update mask if some fields were computed additionally. Name is added as well.
body_mask .google.protobuf.FieldMask If this field is populated, then resource in response will contain only specific fields. If skip_entire_response_body is true, this field is ignored.

DeleteConnectorUserTokenRequest Message

A request message of the DeleteConnectorUserToken method.

Name Type Description
name string (name of ConnectorUserToken) Name of ntt.ai.v1.ConnectorUserToken
allow_missing bool If set to true, and the resource is not found, method will be successful and will not return NotFound error.

Conversation Resource

Conversation Resource

Name patterns:

  • projects/{project}/conversations/{conversation}
  • users/{user}/conversations/{conversation}

Parent resources:

This section covers the methods and messages to interact with Conversation resource.

Conversation Methods

Here is the list of Conversation resource methods:

GetConversation Method

GetConversation

rpc GetConversation(GetConversationRequest) returns (Conversation)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/conversations.get

The equivalent REST API is:

GET /v1/{name=projects/*/conversations/*} 

GET /v1/{name=users/*/conversations/*}

BatchGetConversations Method

BatchGetConversations

rpc BatchGetConversations(BatchGetConversationsRequest) returns (BatchGetConversationsResponse)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/conversations.batchGet

The equivalent REST API is:

GET /v1/conversations:batchGet

ListConversations Method

ListConversations

rpc ListConversations(ListConversationsRequest) returns (ListConversationsResponse)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/conversations.list

The equivalent REST API is:

GET /v1/{parent=projects/*}/conversations 

GET /v1/{parent=users/*}/conversations

WatchConversation Method

WatchConversation

rpc WatchConversation(WatchConversationRequest) returns (WatchConversationResponse)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/conversations.watch

The equivalent REST API is:

POST /v1/{name=projects/*/conversations/*}:watch 

POST /v1/{name=users/*/conversations/*}:watch

WatchConversations Method

WatchConversations

rpc WatchConversations(WatchConversationsRequest) returns (WatchConversationsResponse)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/conversations.watch

The equivalent REST API is:

POST /v1/{parent=projects/*}/conversations:watch 

POST /v1/{parent=users/*}/conversations:watch

CreateConversation Method

CreateConversation

rpc CreateConversation(CreateConversationRequest) returns (Conversation)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/conversations.create

The equivalent REST API is:

POST /v1/{parent=projects/*}/conversations (BODY: conversation)

POST /v1/{parent=users/*}/conversations

UpdateConversation Method

UpdateConversation

rpc UpdateConversation(UpdateConversationRequest) returns (Conversation)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/conversations.update

The equivalent REST API is:

PUT /v1/{conversation.name=projects/*/conversations/*} (BODY: conversation)

PUT /v1/{conversation.name=users/*/conversations/*}

DeleteConversation Method

DeleteConversation

rpc DeleteConversation(DeleteConversationRequest) returns (Empty)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/conversations.delete

The equivalent REST API is:

DELETE /v1/{name=projects/*/conversations/*} 

DELETE /v1/{name=users/*/conversations/*}

SearchConversations Method

SearchConversations

rpc SearchConversations(SearchConversationsRequest) returns (SearchConversationsResponse)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/conversations.search

The equivalent REST API is:

GET /v1/{parent=projects/*}/conversations:search 

GET /v1/{parent=users/*}/conversations:search

CreateConversationFromPrompt Method

CreateConversationFromPrompt

rpc CreateConversationFromPrompt(CreateConversationFromPromptRequest) returns (Conversation)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/conversations.create

The equivalent REST API is:

POST /v1/{parent=projects/*}/conversations:createFromPrompt (BODY: conversation)

POST /v1/{parent=users/*}/conversations:createFromPrompt

Conversation Messages

Here is the list of Conversation resource messages:

Conversation Message

Name Type Description
name string (name of Conversation) Name of Conversation When creating a new instance, this field is optional and if not provided, it will be generated automatically. Last ID segment must conform to the following regex: [a-z][a-z0-9\-]{0,28}[a-z0-9]
metadata Meta Metadata is an object with information like create, update and delete time (for async deleted resources), has user labels/annotations, sharding information, multi-region syncing information and may have non-schema owners (useful for taking ownership of resources belonging to lower level services by higher ones).
title string Auto generated display title for the conversation
configured_title string User configured display title for the conversation
archived bool Whether the conversation has been archived
is_private bool Privacy level - if true, only visible to creator Private conversations are only accessible to the user who created them Shared (non-private) conversations are visible to all project members
last_activity_time .google.protobuf.Timestamp Timestamp of the last activity
turns repeated ConversationTurn Core conversation data - sequence of turns (each turn = one CreateResponse API call)
usage_by_model map<string, ModelUsageStats> Aggregate statistics by model (for easy analytics/billing)
failed_turns repeated ConversationTurn Failed turns - stored separately for audit/debugging These turns ended with STOP_REASON_ERROR and should not be replayed
replaced_turn_groups repeated ReplacedTurnGroup Groups of replaced turns from resume operations Each resume operation creates a new group, preserving context and order
capability_template string (name of CapabilityTemplate) Capability template used for this conversation

GetConversationRequest Message

A request message of the GetConversation method.

Name Type Description
name string (name of Conversation) Name of ntt.ai.v1.Conversation
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetConversationsRequest Message

A request message of the BatchGetConversations method.

Name Type Description
names repeated string (name of Conversation) Names of Conversations
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetConversationsResponse Message

A response message of the BatchGetConversations method.

Name Type Description
conversations repeated Conversation found Conversations
missing repeated string (name of Conversation) list of not found Conversations

ListConversationsRequest Message

A request message of the ListConversations method.

Name Type Description
parent string (parent name of Conversation) Parent name of ntt.ai.v1.Conversation
page_size int32 Requested page size. Server may return fewer Conversations than requested. If unspecified, server will pick an appropriate default.
page_token string (cursor of Conversation) A token identifying a page of results the server should return. Typically, this is the value of ListConversationsResponse.next_page_token.
order_by string (orderBy of Conversation) Order By - https://cloud.google.com/apis/design/design_patterns#list_pagination list of field path with order directive, either ‘asc’ or ‘desc’. If direction is not provided, ‘asc’ is assumed. e.g. “state.nested_field asc, state.something.else desc, theme”
filter string (filter of Conversation) Filter - filter results by field criteria. Simplified SQL-like syntax with following operators: <=, >=, =, !=, <, >, LIKE, CONTAINS (aliases CONTAIN, HAS, HAVE), IN, IS [NOT] NULL
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask
include_paging_info bool Indicates if list response should contain total count and offset (fields current_offset and total_results_count).

ListConversationsResponse Message

A response message of the ListConversations method.

Name Type Description
conversations repeated Conversation The list of Conversations
prev_page_token string (cursor of Conversation) A token to retrieve previous page of results. Pass this value in the ListConversationsRequest.page_token.
next_page_token string (cursor of Conversation) A token to retrieve next page of results. Pass this value in the ListConversationsRequest.page_token.
current_offset int32 Current offset from the first page or 0 if no page tokens were given, paging info was not requested or there was an error while trying to get it). Page index can be computed from offset and limit provided in a request.
total_results_count int32 Number of total Conversations across all pages or 0, if there are no items, paging info was not requested or there was an error while trying to get it.

WatchConversationRequest Message

A request message of the WatchConversation method.

Name Type Description
name string (name of Conversation) Name of ntt.ai.v1.Conversation
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

WatchConversationResponse Message

A response message of the WatchConversation method.

Name Type Description
change ConversationChange

WatchConversationsRequest Message

A request message of the WatchConversations method.

Name Type Description
type WatchType Type of a watch. Identifies how server stream data to a client, which fields in a request are allowed and which fields in response are relevant.
parent string (parent name of Conversation) Parent name of ntt.ai.v1.Conversation
page_size int32 Requested page size. Server may return fewer Conversations than requested. If unspecified, server will pick an appropriate default. Can be populated only for stateful watch type.
page_token string (cursor of Conversation) A token identifying a page of results the server should return. Can be populated only for stateful watch type.
order_by string (orderBy of Conversation) Order By - https://cloud.google.com/apis/design/design_patterns#list_pagination Can be populated only for stateful watch type.
resume_token string A token identifying watch resume point from previous session. Can be populated only for stateless watch type.
starting_time .google.protobuf.Timestamp Point in the time from which we want to start getting updates. This field can be populated only for stateless watch type and if resume token is not known yet. If specified, initial snapshot will NOT be provided. It is assumed client can obtain it using separate means. Watch responses will contain resume tokens which should be used to resume broken connection.
filter string (filter of Conversation) Filter - filter results by field criteria. Simplified SQL-like syntax with following operators: <=, >=, =, !=, <, >, LIKE, CONTAINS (aliases CONTAIN, HAS, HAVE), IN, IS [NOT] NULL
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view Changes to Conversation that don’t affect any of masked fields won’t be sent back.
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask Changes to Conversation that don’t affect any of masked fields won’t be sent back.
max_chunk_size int32 Maximum amount of changes in each response message. Query result response is divided on the server side into chunks with size of a specified amount to limit memory footprint of each message. Responses will hold information whether more elements will continue for the actual change. If unspecified, server will pick an appropriate default.

WatchConversationsResponse Message

A response message of the WatchConversations method.

Name Type Description
conversation_changes repeated ConversationChange Changes of Conversations
is_current bool If request specified max_chunk_size (or this limit was enforced if stateless watch has been chosen), then responses with “full changeset” will be divided into chunks. Client should keep receiving messages and, once is_current has value true, combine this recent message with all previous ones where is_current is false. If this is the first is_current in a whole watch stream, then it means that client should have, at this moment, contain snapshot of the current situation (or more accurately, snapshot of situation at the moment of request). All Conversations will be of type Added/Current (depending on watch_type specified in the request). Further responses will be incremental - however messages may still be chunked and is_current logic still applies. is_current is always true for stateful watch if max_chunk_size was left to 0.
page_token_change WatchConversationsResponse.PageTokenChange When present, PageTokens used for page navigation should be updated. Present only if is_current is true (last chunk).
resume_token string Token that can be used if current connection drops and client needs to reconnect. Populated only for stateless watch type. Present only if is_current is true (last chunk).
snapshot_size int64 Server may occasionally send information how many resources should client have in its state so far (response message without any changes, but with snapshot_size field specified). If client has different value than the one sent by the server, then it should be treated by a client as an error and should reconnect. If value is smaller then 0, then client should ignore this field as unpopulated. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will be never sent together with is_current, is_soft_reset and is_hard_reset flags.
is_soft_reset bool In case of internal issue server may send response message with this flag. It indicates that client should drop all changes from recent responses where is_current is false only! If last message had is_current set to true, client should do nothing and process normally. Resume token received before is still valid. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will never be sent along with is_current, is_hard_reset or snapshot_size.
is_hard_reset bool In case of internal issue server may send response message with this flag. After receiving, client should clear whole state (drop all changes received so far) as server will send new snapshot (Conversations will contains changes of type Current only). Any resume tokens should be discarded as well. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will never be sent along with is_current, is_soft_reset or snapshot_size.

WatchConversationsResponse.PageTokenChange Message

Name Type Description
prev_page_token string (cursor of Conversation) New token to retrieve previous page of results.
next_page_token string (cursor of Conversation) New token to retrieve next page of results.

CreateConversationRequest Message

A request message of the CreateConversation method.

Name Type Description
parent string (parent name of Conversation) Parent name of ntt.ai.v1.Conversation
conversation Conversation Conversation resource body
response_mask CreateConversationRequest.ResponseMask Optional masking applied to response object to reduce message response size.

CreateConversationRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

Name Type Description
skip_entire_response_body bool If this flag has value true, then response will contain just empty resource without any fields populated.
body_mask .google.protobuf.FieldMask If this field is populated, then resource in response will contain only specific fields.

UpdateConversationRequest Message

A request message of the UpdateConversation method.

Name Type Description
conversation Conversation Conversation resource body
update_mask .google.protobuf.FieldMask FieldMask applied to request - change will be applied only for fields in the mask
cas UpdateConversationRequest.CAS Conditional update applied to request if update should be executed only for specific resource state. If this field is populated, then server will fetch existing resource, compare with the one stored in the cas field (after applying field mask) and proceed with update only and only if they match. Otherwise RPC error Aborted will be returned.
allow_missing bool If set to true, and the resource is not found, a new resource will be created. In this situation, ‘field_mask’ is ignored. https://google.aip.dev/134#create-or-update
response_mask UpdateConversationRequest.ResponseMask reduce message response size.

UpdateConversationRequest.CAS Message

CAS - Compare and Swap. This object is used if user wants to make update conditional based upon previous resource version.

Name Type Description
conditional_state Conversation Conditional desired state of a resource before update.
field_mask .google.protobuf.FieldMask Field paths from conditional state of resource server should check and compare.

UpdateConversationRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

Name Type Description
skip_entire_response_body bool If this flag has value true, then response will contain just empty resource without any fields populated. Field body_mask is ignored if set.
updated_fields_only bool Include all fields that were actually updated during processing. Note this may be larger than update mask if some fields were computed additionally. Name is added as well.
body_mask .google.protobuf.FieldMask If this field is populated, then resource in response will contain only specific fields. If skip_entire_response_body is true, this field is ignored.

DeleteConversationRequest Message

A request message of the DeleteConversation method.

Name Type Description
name string (name of Conversation) Name of ntt.ai.v1.Conversation
allow_missing bool If set to true, and the resource is not found, method will be successful and will not return NotFound error.

SearchConversationsRequest Message

A request message of the SearchConversations method.

Name Type Description
parent string (parent name of Conversation) Parent name of ntt.ai.v1.Conversation
page_size int32 Requested page size. Server may return fewer Conversations than requested. If unspecified, server will pick an appropriate default.
page_token string (cursor of Conversation) A token identifying a page of results the server should return. Typically, this is the value of SearchConversationsResponse.next_page_token.
order_by string (orderBy of Conversation) Order By - https://cloud.google.com/apis/design/design_patterns#list_pagination list of field path with order directive, either ‘asc’ or ‘desc’. If direction is not provided, ‘asc’ is assumed. e.g. “state.nested_field asc, state.something.else desc, theme”
filter string (filter of Conversation) Filter - filter results by field criteria. Simplified SQL-like syntax with following operators: <=, >=, =, !=, <, >, LIKE, CONTAINS (aliases CONTAIN, HAS, HAVE), IN, IS [NOT] NULL
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask
phrase string Optional search phrase used to further filter results.

SearchConversationsResponse Message

A response message of the SearchConversations method.

Name Type Description
conversations repeated Conversation The list of Conversations
prev_page_token string (cursor of Conversation) A token to retrieve previous page of results. Pass this value in the SearchConversationsRequest.page_token.
next_page_token string (cursor of Conversation) A token to retrieve next page of results. Pass this value in the SearchConversationsRequest.page_token.
current_offset int32 Current offset from the first page (0 if no page tokens were given). Page index can be computed from offset and limit provided in a request
total_results_count int32 Number of total Conversations across all pages.

CreateConversationFromPromptRequest Message

A request message of the CreateConversationFromPrompt method.

Name Type Description
parent string (parent name of Conversation) Parent name of ntt.ai.v1.Conversation
conversation Conversation Conversation resource body
user_prompt string Initial user prompt used for title generation. Not automatically stored as a turn; server decides how to use it.

ConversationFeedback Resource

ConversationFeedback Resource

Name patterns:

  • projects/{project}/conversations/{conversation}/conversationFeedbacks/{conversation_feedback}
  • users/{user}/conversations/{conversation}/conversationFeedbacks/{conversation_feedback}

Parent resources:

This section covers the methods and messages to interact with ConversationFeedback resource.

ConversationFeedback Methods

Here is the list of ConversationFeedback resource methods:

GetConversationFeedback Method

GetConversationFeedback

rpc GetConversationFeedback(GetConversationFeedbackRequest) returns (ConversationFeedback)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/conversationFeedbacks.get

The equivalent REST API is:

GET /v1/{name=projects/*/conversations/*/conversationFeedbacks/*} 

GET /v1/{name=users/*/conversations/*/conversationFeedbacks/*}

BatchGetConversationFeedbacks Method

BatchGetConversationFeedbacks

rpc BatchGetConversationFeedbacks(BatchGetConversationFeedbacksRequest) returns (BatchGetConversationFeedbacksResponse)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/conversationFeedbacks.batchGet

The equivalent REST API is:

GET /v1/conversationFeedbacks:batchGet

ListConversationFeedbacks Method

ListConversationFeedbacks

rpc ListConversationFeedbacks(ListConversationFeedbacksRequest) returns (ListConversationFeedbacksResponse)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/conversationFeedbacks.list

The equivalent REST API is:

GET /v1/{parent=projects/*/conversations/*}/conversationFeedbacks 

GET /v1/{parent=users/*/conversations/*}/conversationFeedbacks

WatchConversationFeedback Method

WatchConversationFeedback

rpc WatchConversationFeedback(WatchConversationFeedbackRequest) returns (WatchConversationFeedbackResponse)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/conversationFeedbacks.watch

The equivalent REST API is:

POST /v1/{name=projects/*/conversations/*/conversationFeedbacks/*}:watch 

POST /v1/{name=users/*/conversations/*/conversationFeedbacks/*}:watch

WatchConversationFeedbacks Method

WatchConversationFeedbacks

rpc WatchConversationFeedbacks(WatchConversationFeedbacksRequest) returns (WatchConversationFeedbacksResponse)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/conversationFeedbacks.watch

The equivalent REST API is:

POST /v1/{parent=projects/*/conversations/*}/conversationFeedbacks:watch 

POST /v1/{parent=users/*/conversations/*}/conversationFeedbacks:watch

CreateConversationFeedback Method

CreateConversationFeedback

rpc CreateConversationFeedback(CreateConversationFeedbackRequest) returns (ConversationFeedback)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/conversationFeedbacks.create

The equivalent REST API is:

POST /v1/{parent=projects/*/conversations/*}/conversationFeedbacks (BODY: conversation_feedback)

POST /v1/{parent=users/*/conversations/*}/conversationFeedbacks

UpdateConversationFeedback Method

UpdateConversationFeedback

rpc UpdateConversationFeedback(UpdateConversationFeedbackRequest) returns (ConversationFeedback)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/conversationFeedbacks.update

The equivalent REST API is:

PUT /v1/{conversation_feedback.name=projects/*/conversations/*/conversationFeedbacks/*} (BODY: conversation_feedback)

PUT /v1/{conversation_feedback.name=users/*/conversations/*/conversationFeedbacks/*}

DeleteConversationFeedback Method

DeleteConversationFeedback

rpc DeleteConversationFeedback(DeleteConversationFeedbackRequest) returns (Empty)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/conversationFeedbacks.delete

The equivalent REST API is:

DELETE /v1/{name=projects/*/conversations/*/conversationFeedbacks/*} 

DELETE /v1/{name=users/*/conversations/*/conversationFeedbacks/*}

ConversationFeedback Messages

Here is the list of ConversationFeedback resource messages:

ConversationFeedback Message

Name Type Description
name string (name of ConversationFeedback) Name of ConversationFeedback When creating a new instance, this field is optional and if not provided, it will be generated automatically. Last ID segment must conform to the following regex: [a-z][a-z0-9\-]{0,28}[a-z0-9]
metadata Meta Metadata is an object with information like create, update and delete time (for async deleted resources), has user labels/annotations, sharding information, multi-region syncing information and may have non-schema owners (useful for taking ownership of resources belonging to lower level services by higher ones).
rating int32 Rating scale 1 to 10
comment string Optional free-form comment
tags repeated string Structured tags for analytics (e.g., “helpful”, “incorrect”)
created_at .google.protobuf.Timestamp Server-populated timestamp when feedback was created
user_email string Server-populated email of the user who submitted feedback

GetConversationFeedbackRequest Message

A request message of the GetConversationFeedback method.

Name Type Description
name string (name of ConversationFeedback) Name of ntt.ai.v1.ConversationFeedback
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetConversationFeedbacksRequest Message

A request message of the BatchGetConversationFeedbacks method.

Name Type Description
names repeated string (name of ConversationFeedback) Names of ConversationFeedbacks
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetConversationFeedbacksResponse Message

A response message of the BatchGetConversationFeedbacks method.

Name Type Description
conversation_feedbacks repeated ConversationFeedback found ConversationFeedbacks
missing repeated string (name of ConversationFeedback) list of not found ConversationFeedbacks

ListConversationFeedbacksRequest Message

A request message of the ListConversationFeedbacks method.

Name Type Description
parent string (parent name of ConversationFeedback) Parent name of ntt.ai.v1.ConversationFeedback
page_size int32 Requested page size. Server may return fewer ConversationFeedbacks than requested. If unspecified, server will pick an appropriate default.
page_token string (cursor of ConversationFeedback) A token identifying a page of results the server should return. Typically, this is the value of ListConversationFeedbacksResponse.next_page_token.
order_by string (orderBy of ConversationFeedback) Order By - https://cloud.google.com/apis/design/design_patterns#list_pagination list of field path with order directive, either ‘asc’ or ‘desc’. If direction is not provided, ‘asc’ is assumed. e.g. “state.nested_field asc, state.something.else desc, theme”
filter string (filter of ConversationFeedback) Filter - filter results by field criteria. Simplified SQL-like syntax with following operators: <=, >=, =, !=, <, >, LIKE, CONTAINS (aliases CONTAIN, HAS, HAVE), IN, IS [NOT] NULL
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask
include_paging_info bool Indicates if list response should contain total count and offset (fields current_offset and total_results_count).

ListConversationFeedbacksResponse Message

A response message of the ListConversationFeedbacks method.

Name Type Description
conversation_feedbacks repeated ConversationFeedback The list of ConversationFeedbacks
prev_page_token string (cursor of ConversationFeedback) A token to retrieve previous page of results. Pass this value in the ListConversationFeedbacksRequest.page_token.
next_page_token string (cursor of ConversationFeedback) A token to retrieve next page of results. Pass this value in the ListConversationFeedbacksRequest.page_token.
current_offset int32 Current offset from the first page or 0 if no page tokens were given, paging info was not requested or there was an error while trying to get it). Page index can be computed from offset and limit provided in a request.
total_results_count int32 Number of total ConversationFeedbacks across all pages or 0, if there are no items, paging info was not requested or there was an error while trying to get it.

WatchConversationFeedbackRequest Message

A request message of the WatchConversationFeedback method.

Name Type Description
name string (name of ConversationFeedback) Name of ntt.ai.v1.ConversationFeedback
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

WatchConversationFeedbackResponse Message

A response message of the WatchConversationFeedback method.

Name Type Description
change ConversationFeedbackChange

WatchConversationFeedbacksRequest Message

A request message of the WatchConversationFeedbacks method.

Name Type Description
type WatchType Type of a watch. Identifies how server stream data to a client, which fields in a request are allowed and which fields in response are relevant.
parent string (parent name of ConversationFeedback) Parent name of ntt.ai.v1.ConversationFeedback
page_size int32 Requested page size. Server may return fewer ConversationFeedbacks than requested. If unspecified, server will pick an appropriate default. Can be populated only for stateful watch type.
page_token string (cursor of ConversationFeedback) A token identifying a page of results the server should return. Can be populated only for stateful watch type.
order_by string (orderBy of ConversationFeedback) Order By - https://cloud.google.com/apis/design/design_patterns#list_pagination Can be populated only for stateful watch type.
resume_token string A token identifying watch resume point from previous session. Can be populated only for stateless watch type.
starting_time .google.protobuf.Timestamp Point in the time from which we want to start getting updates. This field can be populated only for stateless watch type and if resume token is not known yet. If specified, initial snapshot will NOT be provided. It is assumed client can obtain it using separate means. Watch responses will contain resume tokens which should be used to resume broken connection.
filter string (filter of ConversationFeedback) Filter - filter results by field criteria. Simplified SQL-like syntax with following operators: <=, >=, =, !=, <, >, LIKE, CONTAINS (aliases CONTAIN, HAS, HAVE), IN, IS [NOT] NULL
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view Changes to ConversationFeedback that don’t affect any of masked fields won’t be sent back.
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask Changes to ConversationFeedback that don’t affect any of masked fields won’t be sent back.
max_chunk_size int32 Maximum amount of changes in each response message. Query result response is divided on the server side into chunks with size of a specified amount to limit memory footprint of each message. Responses will hold information whether more elements will continue for the actual change. If unspecified, server will pick an appropriate default.

WatchConversationFeedbacksResponse Message

A response message of the WatchConversationFeedbacks method.

Name Type Description
conversation_feedback_changes repeated ConversationFeedbackChange Changes of ConversationFeedbacks
is_current bool If request specified max_chunk_size (or this limit was enforced if stateless watch has been chosen), then responses with “full changeset” will be divided into chunks. Client should keep receiving messages and, once is_current has value true, combine this recent message with all previous ones where is_current is false. If this is the first is_current in a whole watch stream, then it means that client should have, at this moment, contain snapshot of the current situation (or more accurately, snapshot of situation at the moment of request). All ConversationFeedbacks will be of type Added/Current (depending on watch_type specified in the request). Further responses will be incremental - however messages may still be chunked and is_current logic still applies. is_current is always true for stateful watch if max_chunk_size was left to 0.
page_token_change WatchConversationFeedbacksResponse.PageTokenChange When present, PageTokens used for page navigation should be updated. Present only if is_current is true (last chunk).
resume_token string Token that can be used if current connection drops and client needs to reconnect. Populated only for stateless watch type. Present only if is_current is true (last chunk).
snapshot_size int64 Server may occasionally send information how many resources should client have in its state so far (response message without any changes, but with snapshot_size field specified). If client has different value than the one sent by the server, then it should be treated by a client as an error and should reconnect. If value is smaller then 0, then client should ignore this field as unpopulated. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will be never sent together with is_current, is_soft_reset and is_hard_reset flags.
is_soft_reset bool In case of internal issue server may send response message with this flag. It indicates that client should drop all changes from recent responses where is_current is false only! If last message had is_current set to true, client should do nothing and process normally. Resume token received before is still valid. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will never be sent along with is_current, is_hard_reset or snapshot_size.
is_hard_reset bool In case of internal issue server may send response message with this flag. After receiving, client should clear whole state (drop all changes received so far) as server will send new snapshot (ConversationFeedbacks will contains changes of type Current only). Any resume tokens should be discarded as well. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will never be sent along with is_current, is_soft_reset or snapshot_size.

WatchConversationFeedbacksResponse.PageTokenChange Message

Name Type Description
prev_page_token string (cursor of ConversationFeedback) New token to retrieve previous page of results.
next_page_token string (cursor of ConversationFeedback) New token to retrieve next page of results.

CreateConversationFeedbackRequest Message

A request message of the CreateConversationFeedback method.

Name Type Description
parent string (parent name of ConversationFeedback) Parent name of ntt.ai.v1.ConversationFeedback
conversation_feedback ConversationFeedback ConversationFeedback resource body
response_mask CreateConversationFeedbackRequest.ResponseMask Optional masking applied to response object to reduce message response size.

CreateConversationFeedbackRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

Name Type Description
skip_entire_response_body bool If this flag has value true, then response will contain just empty resource without any fields populated.
body_mask .google.protobuf.FieldMask If this field is populated, then resource in response will contain only specific fields.

UpdateConversationFeedbackRequest Message

A request message of the UpdateConversationFeedback method.

Name Type Description
conversation_feedback ConversationFeedback ConversationFeedback resource body
update_mask .google.protobuf.FieldMask FieldMask applied to request - change will be applied only for fields in the mask
cas UpdateConversationFeedbackRequest.CAS Conditional update applied to request if update should be executed only for specific resource state. If this field is populated, then server will fetch existing resource, compare with the one stored in the cas field (after applying field mask) and proceed with update only and only if they match. Otherwise RPC error Aborted will be returned.
allow_missing bool If set to true, and the resource is not found, a new resource will be created. In this situation, ‘field_mask’ is ignored. https://google.aip.dev/134#create-or-update
response_mask UpdateConversationFeedbackRequest.ResponseMask reduce message response size.

UpdateConversationFeedbackRequest.CAS Message

CAS - Compare and Swap. This object is used if user wants to make update conditional based upon previous resource version.

Name Type Description
conditional_state ConversationFeedback Conditional desired state of a resource before update.
field_mask .google.protobuf.FieldMask Field paths from conditional state of resource server should check and compare.

UpdateConversationFeedbackRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

Name Type Description
skip_entire_response_body bool If this flag has value true, then response will contain just empty resource without any fields populated. Field body_mask is ignored if set.
updated_fields_only bool Include all fields that were actually updated during processing. Note this may be larger than update mask if some fields were computed additionally. Name is added as well.
body_mask .google.protobuf.FieldMask If this field is populated, then resource in response will contain only specific fields. If skip_entire_response_body is true, this field is ignored.

DeleteConversationFeedbackRequest Message

A request message of the DeleteConversationFeedback method.

Name Type Description
name string (name of ConversationFeedback) Name of ntt.ai.v1.ConversationFeedback
allow_missing bool If set to true, and the resource is not found, method will be successful and will not return NotFound error.

Document Resource

Document Resource represents specific document in a search index. When uploaded to the service, it is automatically tokenized and chunked in search service. As of now, each Document must be some kind of text file (markdown, protobuf, source code, json, yaml…).

Name patterns:

  • searchDbs/{search_db}/searchIndices/{search_index}/documents/{document}
  • projects/{project}/searchDbs/{search_db}/searchIndices/{search_index}/documents/{document}

Parent resources:

This section covers the methods and messages to interact with Document resource.

Document Methods

Here is the list of Document resource methods:

GetDocument Method

GetDocument

rpc GetDocument(GetDocumentRequest) returns (Document)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/documents.get

The equivalent REST API is:

GET /v1/{name=searchDbs/*/searchIndices/*/documents/*} 

GET /v1/{name=projects/*/searchDbs/*/searchIndices/*/documents/*}

BatchGetDocuments Method

BatchGetDocuments

rpc BatchGetDocuments(BatchGetDocumentsRequest) returns (BatchGetDocumentsResponse)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/documents.batchGet

The equivalent REST API is:

GET /v1/documents:batchGet

ListDocuments Method

ListDocuments

rpc ListDocuments(ListDocumentsRequest) returns (ListDocumentsResponse)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/documents.list

The equivalent REST API is:

GET /v1/{parent=searchDbs/*/searchIndices/*}/documents 

GET /v1/{parent=projects/*/searchDbs/*/searchIndices/*}/documents

WatchDocument Method

WatchDocument

rpc WatchDocument(WatchDocumentRequest) returns (WatchDocumentResponse)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/documents.watch

The equivalent REST API is:

POST /v1/{name=searchDbs/*/searchIndices/*/documents/*}:watch 

POST /v1/{name=projects/*/searchDbs/*/searchIndices/*/documents/*}:watch

WatchDocuments Method

WatchDocuments

rpc WatchDocuments(WatchDocumentsRequest) returns (WatchDocumentsResponse)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/documents.watch

The equivalent REST API is:

POST /v1/{parent=searchDbs/*/searchIndices/*}/documents:watch 

POST /v1/{parent=projects/*/searchDbs/*/searchIndices/*}/documents:watch

CreateDocument Method

CreateDocument

rpc CreateDocument(CreateDocumentRequest) returns (Document)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/documents.create

The equivalent REST API is:

POST /v1/{parent=searchDbs/*/searchIndices/*}/documents (BODY: document)

POST /v1/{parent=projects/*/searchDbs/*/searchIndices/*}/documents

UpdateDocument Method

UpdateDocument

rpc UpdateDocument(UpdateDocumentRequest) returns (Document)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/documents.update

The equivalent REST API is:

PUT /v1/{document.name=searchDbs/*/searchIndices/*/documents/*} (BODY: document)

PUT /v1/{document.name=projects/*/searchDbs/*/searchIndices/*/documents/*}

DeleteDocument Method

DeleteDocument

rpc DeleteDocument(DeleteDocumentRequest) returns (Empty)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/documents.delete

The equivalent REST API is:

DELETE /v1/{name=searchDbs/*/searchIndices/*/documents/*} 

DELETE /v1/{name=projects/*/searchDbs/*/searchIndices/*/documents/*}

Document Messages

Here is the list of Document resource messages:

Document Message

Name Type Description
name string (name of Document) Name of Document When creating a new instance, this field is optional and if not provided, it will be generated automatically. Last ID segment must conform to the following regex: [a-z][a-z0-9\-]{0,28}[a-z0-9]
metadata Meta Metadata is an object with information like create, update and delete time (for async deleted resources), has user labels/annotations, sharding information, multi-region syncing information and may have non-schema owners (useful for taking ownership of resources belonging to lower level services by higher ones).
content bytes Document contents.
checksum string Computed based on checksum. Checksum can be used to later determine if file needs to be updated or not.
title string
title_prefix string
file_type Document.FileType

GetDocumentRequest Message

A request message of the GetDocument method.

Name Type Description
name string (name of Document) Name of ntt.ai.v1.Document
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetDocumentsRequest Message

A request message of the BatchGetDocuments method.

Name Type Description
names repeated string (name of Document) Names of Documents
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetDocumentsResponse Message

A response message of the BatchGetDocuments method.

Name Type Description
documents repeated Document found Documents
missing repeated string (name of Document) list of not found Documents

ListDocumentsRequest Message

A request message of the ListDocuments method.

Name Type Description
parent string (parent name of Document) Parent name of ntt.ai.v1.Document
page_size int32 Requested page size. Server may return fewer Documents than requested. If unspecified, server will pick an appropriate default.
page_token string (cursor of Document) A token identifying a page of results the server should return. Typically, this is the value of ListDocumentsResponse.next_page_token.
order_by string (orderBy of Document) Order By - https://cloud.google.com/apis/design/design_patterns#list_pagination list of field path with order directive, either ‘asc’ or ‘desc’. If direction is not provided, ‘asc’ is assumed. e.g. “state.nested_field asc, state.something.else desc, theme”
filter string (filter of Document) Filter - filter results by field criteria. Simplified SQL-like syntax with following operators: <=, >=, =, !=, <, >, LIKE, CONTAINS (aliases CONTAIN, HAS, HAVE), IN, IS [NOT] NULL
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask
include_paging_info bool Indicates if list response should contain total count and offset (fields current_offset and total_results_count).

ListDocumentsResponse Message

A response message of the ListDocuments method.

Name Type Description
documents repeated Document The list of Documents
prev_page_token string (cursor of Document) A token to retrieve previous page of results. Pass this value in the ListDocumentsRequest.page_token.
next_page_token string (cursor of Document) A token to retrieve next page of results. Pass this value in the ListDocumentsRequest.page_token.
current_offset int32 Current offset from the first page or 0 if no page tokens were given, paging info was not requested or there was an error while trying to get it). Page index can be computed from offset and limit provided in a request.
total_results_count int32 Number of total Documents across all pages or 0, if there are no items, paging info was not requested or there was an error while trying to get it.

WatchDocumentRequest Message

A request message of the WatchDocument method.

Name Type Description
name string (name of Document) Name of ntt.ai.v1.Document
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

WatchDocumentResponse Message

A response message of the WatchDocument method.

Name Type Description
change DocumentChange

WatchDocumentsRequest Message

A request message of the WatchDocuments method.

Name Type Description
type WatchType Type of a watch. Identifies how server stream data to a client, which fields in a request are allowed and which fields in response are relevant.
parent string (parent name of Document) Parent name of ntt.ai.v1.Document
page_size int32 Requested page size. Server may return fewer Documents than requested. If unspecified, server will pick an appropriate default. Can be populated only for stateful watch type.
page_token string (cursor of Document) A token identifying a page of results the server should return. Can be populated only for stateful watch type.
order_by string (orderBy of Document) Order By - https://cloud.google.com/apis/design/design_patterns#list_pagination Can be populated only for stateful watch type.
resume_token string A token identifying watch resume point from previous session. Can be populated only for stateless watch type.
starting_time .google.protobuf.Timestamp Point in the time from which we want to start getting updates. This field can be populated only for stateless watch type and if resume token is not known yet. If specified, initial snapshot will NOT be provided. It is assumed client can obtain it using separate means. Watch responses will contain resume tokens which should be used to resume broken connection.
filter string (filter of Document) Filter - filter results by field criteria. Simplified SQL-like syntax with following operators: <=, >=, =, !=, <, >, LIKE, CONTAINS (aliases CONTAIN, HAS, HAVE), IN, IS [NOT] NULL
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view Changes to Document that don’t affect any of masked fields won’t be sent back.
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask Changes to Document that don’t affect any of masked fields won’t be sent back.
max_chunk_size int32 Maximum amount of changes in each response message. Query result response is divided on the server side into chunks with size of a specified amount to limit memory footprint of each message. Responses will hold information whether more elements will continue for the actual change. If unspecified, server will pick an appropriate default.

WatchDocumentsResponse Message

A response message of the WatchDocuments method.

Name Type Description
document_changes repeated DocumentChange Changes of Documents
is_current bool If request specified max_chunk_size (or this limit was enforced if stateless watch has been chosen), then responses with “full changeset” will be divided into chunks. Client should keep receiving messages and, once is_current has value true, combine this recent message with all previous ones where is_current is false. If this is the first is_current in a whole watch stream, then it means that client should have, at this moment, contain snapshot of the current situation (or more accurately, snapshot of situation at the moment of request). All Documents will be of type Added/Current (depending on watch_type specified in the request). Further responses will be incremental - however messages may still be chunked and is_current logic still applies. is_current is always true for stateful watch if max_chunk_size was left to 0.
page_token_change WatchDocumentsResponse.PageTokenChange When present, PageTokens used for page navigation should be updated. Present only if is_current is true (last chunk).
resume_token string Token that can be used if current connection drops and client needs to reconnect. Populated only for stateless watch type. Present only if is_current is true (last chunk).
snapshot_size int64 Server may occasionally send information how many resources should client have in its state so far (response message without any changes, but with snapshot_size field specified). If client has different value than the one sent by the server, then it should be treated by a client as an error and should reconnect. If value is smaller then 0, then client should ignore this field as unpopulated. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will be never sent together with is_current, is_soft_reset and is_hard_reset flags.
is_soft_reset bool In case of internal issue server may send response message with this flag. It indicates that client should drop all changes from recent responses where is_current is false only! If last message had is_current set to true, client should do nothing and process normally. Resume token received before is still valid. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will never be sent along with is_current, is_hard_reset or snapshot_size.
is_hard_reset bool In case of internal issue server may send response message with this flag. After receiving, client should clear whole state (drop all changes received so far) as server will send new snapshot (Documents will contains changes of type Current only). Any resume tokens should be discarded as well. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will never be sent along with is_current, is_soft_reset or snapshot_size.

WatchDocumentsResponse.PageTokenChange Message

Name Type Description
prev_page_token string (cursor of Document) New token to retrieve previous page of results.
next_page_token string (cursor of Document) New token to retrieve next page of results.

CreateDocumentRequest Message

A request message of the CreateDocument method.

Name Type Description
parent string (parent name of Document) Parent name of ntt.ai.v1.Document
document Document Document resource body
response_mask CreateDocumentRequest.ResponseMask Optional masking applied to response object to reduce message response size.

CreateDocumentRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

Name Type Description
skip_entire_response_body bool If this flag has value true, then response will contain just empty resource without any fields populated.
body_mask .google.protobuf.FieldMask If this field is populated, then resource in response will contain only specific fields.

UpdateDocumentRequest Message

A request message of the UpdateDocument method.

Name Type Description
document Document Document resource body
update_mask .google.protobuf.FieldMask FieldMask applied to request - change will be applied only for fields in the mask
cas UpdateDocumentRequest.CAS Conditional update applied to request if update should be executed only for specific resource state. If this field is populated, then server will fetch existing resource, compare with the one stored in the cas field (after applying field mask) and proceed with update only and only if they match. Otherwise RPC error Aborted will be returned.
allow_missing bool If set to true, and the resource is not found, a new resource will be created. In this situation, ‘field_mask’ is ignored. https://google.aip.dev/134#create-or-update
response_mask UpdateDocumentRequest.ResponseMask reduce message response size.

UpdateDocumentRequest.CAS Message

CAS - Compare and Swap. This object is used if user wants to make update conditional based upon previous resource version.

Name Type Description
conditional_state Document Conditional desired state of a resource before update.
field_mask .google.protobuf.FieldMask Field paths from conditional state of resource server should check and compare.

UpdateDocumentRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

Name Type Description
skip_entire_response_body bool If this flag has value true, then response will contain just empty resource without any fields populated. Field body_mask is ignored if set.
updated_fields_only bool Include all fields that were actually updated during processing. Note this may be larger than update mask if some fields were computed additionally. Name is added as well.
body_mask .google.protobuf.FieldMask If this field is populated, then resource in response will contain only specific fields. If skip_entire_response_body is true, this field is ignored.

DeleteDocumentRequest Message

A request message of the DeleteDocument method.

Name Type Description
name string (name of Document) Name of ntt.ai.v1.Document
allow_missing bool If set to true, and the resource is not found, method will be successful and will not return NotFound error.

Document Enumerations

Here is the list of Document resource enumerations:

Document.FileType Enumeration

Name Description
UNDEFINED
MARKDOWN
GOLANG
PROTOBUF

SearchDb Resource

SearchDb Resource represents access to Search Service, which typically should be some kind of Vector database. It is a container for search indices, which can be used for chat purposes (RAG).

Name patterns:

  • searchDbs/{search_db}
  • projects/{project}/searchDbs/{search_db}

Parent resources:

This section covers the methods and messages to interact with SearchDb resource.

SearchDb Methods

Here is the list of SearchDb resource methods:

GetSearchDb Method

GetSearchDb

rpc GetSearchDb(GetSearchDbRequest) returns (SearchDb)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/searchDbs.get

The equivalent REST API is:

GET /v1/{name=searchDbs/*} 

GET /v1/{name=projects/*/searchDbs/*}

BatchGetSearchDbs Method

BatchGetSearchDbs

rpc BatchGetSearchDbs(BatchGetSearchDbsRequest) returns (BatchGetSearchDbsResponse)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/searchDbs.batchGet

The equivalent REST API is:

GET /v1/searchDbs:batchGet

ListSearchDbs Method

ListSearchDbs

rpc ListSearchDbs(ListSearchDbsRequest) returns (ListSearchDbsResponse)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/searchDbs.list

The equivalent REST API is:

GET /v1/searchDbs 

GET /v1/{parent=projects/*}/searchDbs

WatchSearchDb Method

WatchSearchDb

rpc WatchSearchDb(WatchSearchDbRequest) returns (WatchSearchDbResponse)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/searchDbs.watch

The equivalent REST API is:

POST /v1/{name=searchDbs/*}:watch 

POST /v1/{name=projects/*/searchDbs/*}:watch

WatchSearchDbs Method

WatchSearchDbs

rpc WatchSearchDbs(WatchSearchDbsRequest) returns (WatchSearchDbsResponse)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/searchDbs.watch

The equivalent REST API is:

POST /v1/searchDbs:watch 

POST /v1/{parent=projects/*}/searchDbs:watch

CreateSearchDb Method

CreateSearchDb

rpc CreateSearchDb(CreateSearchDbRequest) returns (SearchDb)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/searchDbs.create

The equivalent REST API is:

POST /v1/searchDbs (BODY: search_db)

POST /v1/{parent=projects/*}/searchDbs

UpdateSearchDb Method

UpdateSearchDb

rpc UpdateSearchDb(UpdateSearchDbRequest) returns (SearchDb)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/searchDbs.update

The equivalent REST API is:

PUT /v1/{search_db.name=searchDbs/*} (BODY: search_db)

PUT /v1/{search_db.name=projects/*/searchDbs/*}

DeleteSearchDb Method

DeleteSearchDb

rpc DeleteSearchDb(DeleteSearchDbRequest) returns (Empty)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/searchDbs.delete

The equivalent REST API is:

DELETE /v1/{name=searchDbs/*} 

DELETE /v1/{name=projects/*/searchDbs/*}

SearchDb Messages

Here is the list of SearchDb resource messages:

SearchDb Message

Name Type Description
name string (name of SearchDb) Name of SearchDb When creating a new instance, this field is optional and if not provided, it will be generated automatically. Last ID segment must conform to the following regex: [a-z][a-z0-9\-]{0,28}[a-z0-9]
metadata Meta Metadata is an object with information like create, update and delete time (for async deleted resources), has user labels/annotations, sharding information, multi-region syncing information and may have non-schema owners (useful for taking ownership of resources belonging to lower level services by higher ones).
azure_ai_search SearchDb.AzureAiSearch

SearchDb.AzureAiSearch Message

Name Type Description
endpoint string
api_key string (reference to Secret)
enable_semantic bool Whether to enable semantic search features (requires Basic+ tier with semantic enabled)

GetSearchDbRequest Message

A request message of the GetSearchDb method.

Name Type Description
name string (name of SearchDb) Name of ntt.ai.v1.SearchDb
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetSearchDbsRequest Message

A request message of the BatchGetSearchDbs method.

Name Type Description
names repeated string (name of SearchDb) Names of SearchDbs
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetSearchDbsResponse Message

A response message of the BatchGetSearchDbs method.

Name Type Description
search_dbs repeated SearchDb found SearchDbs
missing repeated string (name of SearchDb) list of not found SearchDbs

ListSearchDbsRequest Message

A request message of the ListSearchDbs method.

Name Type Description
parent string (parent name of SearchDb) Parent name of ntt.ai.v1.SearchDb
page_size int32 Requested page size. Server may return fewer SearchDbs than requested. If unspecified, server will pick an appropriate default.
page_token string (cursor of SearchDb) A token identifying a page of results the server should return. Typically, this is the value of ListSearchDbsResponse.next_page_token.
order_by string (orderBy of SearchDb) Order By - https://cloud.google.com/apis/design/design_patterns#list_pagination list of field path with order directive, either ‘asc’ or ‘desc’. If direction is not provided, ‘asc’ is assumed. e.g. “state.nested_field asc, state.something.else desc, theme”
filter string (filter of SearchDb) Filter - filter results by field criteria. Simplified SQL-like syntax with following operators: <=, >=, =, !=, <, >, LIKE, CONTAINS (aliases CONTAIN, HAS, HAVE), IN, IS [NOT] NULL
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask
include_paging_info bool Indicates if list response should contain total count and offset (fields current_offset and total_results_count).

ListSearchDbsResponse Message

A response message of the ListSearchDbs method.

Name Type Description
search_dbs repeated SearchDb The list of SearchDbs
prev_page_token string (cursor of SearchDb) A token to retrieve previous page of results. Pass this value in the ListSearchDbsRequest.page_token.
next_page_token string (cursor of SearchDb) A token to retrieve next page of results. Pass this value in the ListSearchDbsRequest.page_token.
current_offset int32 Current offset from the first page or 0 if no page tokens were given, paging info was not requested or there was an error while trying to get it). Page index can be computed from offset and limit provided in a request.
total_results_count int32 Number of total SearchDbs across all pages or 0, if there are no items, paging info was not requested or there was an error while trying to get it.

WatchSearchDbRequest Message

A request message of the WatchSearchDb method.

Name Type Description
name string (name of SearchDb) Name of ntt.ai.v1.SearchDb
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

WatchSearchDbResponse Message

A response message of the WatchSearchDb method.

Name Type Description
change SearchDbChange

WatchSearchDbsRequest Message

A request message of the WatchSearchDbs method.

Name Type Description
type WatchType Type of a watch. Identifies how server stream data to a client, which fields in a request are allowed and which fields in response are relevant.
parent string (parent name of SearchDb) Parent name of ntt.ai.v1.SearchDb
page_size int32 Requested page size. Server may return fewer SearchDbs than requested. If unspecified, server will pick an appropriate default. Can be populated only for stateful watch type.
page_token string (cursor of SearchDb) A token identifying a page of results the server should return. Can be populated only for stateful watch type.
order_by string (orderBy of SearchDb) Order By - https://cloud.google.com/apis/design/design_patterns#list_pagination Can be populated only for stateful watch type.
resume_token string A token identifying watch resume point from previous session. Can be populated only for stateless watch type.
starting_time .google.protobuf.Timestamp Point in the time from which we want to start getting updates. This field can be populated only for stateless watch type and if resume token is not known yet. If specified, initial snapshot will NOT be provided. It is assumed client can obtain it using separate means. Watch responses will contain resume tokens which should be used to resume broken connection.
filter string (filter of SearchDb) Filter - filter results by field criteria. Simplified SQL-like syntax with following operators: <=, >=, =, !=, <, >, LIKE, CONTAINS (aliases CONTAIN, HAS, HAVE), IN, IS [NOT] NULL
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view Changes to SearchDb that don’t affect any of masked fields won’t be sent back.
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask Changes to SearchDb that don’t affect any of masked fields won’t be sent back.
max_chunk_size int32 Maximum amount of changes in each response message. Query result response is divided on the server side into chunks with size of a specified amount to limit memory footprint of each message. Responses will hold information whether more elements will continue for the actual change. If unspecified, server will pick an appropriate default.

WatchSearchDbsResponse Message

A response message of the WatchSearchDbs method.

Name Type Description
search_db_changes repeated SearchDbChange Changes of SearchDbs
is_current bool If request specified max_chunk_size (or this limit was enforced if stateless watch has been chosen), then responses with “full changeset” will be divided into chunks. Client should keep receiving messages and, once is_current has value true, combine this recent message with all previous ones where is_current is false. If this is the first is_current in a whole watch stream, then it means that client should have, at this moment, contain snapshot of the current situation (or more accurately, snapshot of situation at the moment of request). All SearchDbs will be of type Added/Current (depending on watch_type specified in the request). Further responses will be incremental - however messages may still be chunked and is_current logic still applies. is_current is always true for stateful watch if max_chunk_size was left to 0.
page_token_change WatchSearchDbsResponse.PageTokenChange When present, PageTokens used for page navigation should be updated. Present only if is_current is true (last chunk).
resume_token string Token that can be used if current connection drops and client needs to reconnect. Populated only for stateless watch type. Present only if is_current is true (last chunk).
snapshot_size int64 Server may occasionally send information how many resources should client have in its state so far (response message without any changes, but with snapshot_size field specified). If client has different value than the one sent by the server, then it should be treated by a client as an error and should reconnect. If value is smaller then 0, then client should ignore this field as unpopulated. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will be never sent together with is_current, is_soft_reset and is_hard_reset flags.
is_soft_reset bool In case of internal issue server may send response message with this flag. It indicates that client should drop all changes from recent responses where is_current is false only! If last message had is_current set to true, client should do nothing and process normally. Resume token received before is still valid. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will never be sent along with is_current, is_hard_reset or snapshot_size.
is_hard_reset bool In case of internal issue server may send response message with this flag. After receiving, client should clear whole state (drop all changes received so far) as server will send new snapshot (SearchDbs will contains changes of type Current only). Any resume tokens should be discarded as well. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will never be sent along with is_current, is_soft_reset or snapshot_size.

WatchSearchDbsResponse.PageTokenChange Message

Name Type Description
prev_page_token string (cursor of SearchDb) New token to retrieve previous page of results.
next_page_token string (cursor of SearchDb) New token to retrieve next page of results.

CreateSearchDbRequest Message

A request message of the CreateSearchDb method.

Name Type Description
parent string (parent name of SearchDb) Parent name of ntt.ai.v1.SearchDb
search_db SearchDb SearchDb resource body
response_mask CreateSearchDbRequest.ResponseMask Optional masking applied to response object to reduce message response size.

CreateSearchDbRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

Name Type Description
skip_entire_response_body bool If this flag has value true, then response will contain just empty resource without any fields populated.
body_mask .google.protobuf.FieldMask If this field is populated, then resource in response will contain only specific fields.

UpdateSearchDbRequest Message

A request message of the UpdateSearchDb method.

Name Type Description
search_db SearchDb SearchDb resource body
update_mask .google.protobuf.FieldMask FieldMask applied to request - change will be applied only for fields in the mask
cas UpdateSearchDbRequest.CAS Conditional update applied to request if update should be executed only for specific resource state. If this field is populated, then server will fetch existing resource, compare with the one stored in the cas field (after applying field mask) and proceed with update only and only if they match. Otherwise RPC error Aborted will be returned.
allow_missing bool If set to true, and the resource is not found, a new resource will be created. In this situation, ‘field_mask’ is ignored. https://google.aip.dev/134#create-or-update
response_mask UpdateSearchDbRequest.ResponseMask reduce message response size.

UpdateSearchDbRequest.CAS Message

CAS - Compare and Swap. This object is used if user wants to make update conditional based upon previous resource version.

Name Type Description
conditional_state SearchDb Conditional desired state of a resource before update.
field_mask .google.protobuf.FieldMask Field paths from conditional state of resource server should check and compare.

UpdateSearchDbRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

Name Type Description
skip_entire_response_body bool If this flag has value true, then response will contain just empty resource without any fields populated. Field body_mask is ignored if set.
updated_fields_only bool Include all fields that were actually updated during processing. Note this may be larger than update mask if some fields were computed additionally. Name is added as well.
body_mask .google.protobuf.FieldMask If this field is populated, then resource in response will contain only specific fields. If skip_entire_response_body is true, this field is ignored.

DeleteSearchDbRequest Message

A request message of the DeleteSearchDb method.

Name Type Description
name string (name of SearchDb) Name of ntt.ai.v1.SearchDb
allow_missing bool If set to true, and the resource is not found, method will be successful and will not return NotFound error.

SearchIndex Resource

SearchIndex Resource represents set of related documents focused on concrete topic. Such an index can be used with Chat service (RAG). Index fields in search database are:

  • ID (contains chunk index with document file name, or url/title)
  • DocumentChecksum (string, maps one to 1 with Document resource).
  • Parent ID (applicable for some documents, like markdown file split by titles).
  • Content (text content after chunking)
  • Title (string, if applicable, depending on a file)
  • URL (string, if applicable, depending on document type)
  • Filepath (string, if applicable, depending on document type)

Name patterns:

  • searchDbs/{search_db}/searchIndices/{search_index}
  • projects/{project}/searchDbs/{search_db}/searchIndices/{search_index}

Parent resources:

This section covers the methods and messages to interact with SearchIndex resource.

SearchIndex Methods

Here is the list of SearchIndex resource methods:

GetSearchIndex Method

GetSearchIndex

rpc GetSearchIndex(GetSearchIndexRequest) returns (SearchIndex)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/searchIndices.get

The equivalent REST API is:

GET /v1/{name=searchDbs/*/searchIndices/*} 

GET /v1/{name=projects/*/searchDbs/*/searchIndices/*}

BatchGetSearchIndices Method

BatchGetSearchIndices

rpc BatchGetSearchIndices(BatchGetSearchIndicesRequest) returns (BatchGetSearchIndicesResponse)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/searchIndices.batchGet

The equivalent REST API is:

GET /v1/searchIndices:batchGet

ListSearchIndices Method

ListSearchIndices

rpc ListSearchIndices(ListSearchIndicesRequest) returns (ListSearchIndicesResponse)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/searchIndices.list

The equivalent REST API is:

GET /v1/{parent=searchDbs/*}/searchIndices 

GET /v1/{parent=projects/*/searchDbs/*}/searchIndices

WatchSearchIndex Method

WatchSearchIndex

rpc WatchSearchIndex(WatchSearchIndexRequest) returns (WatchSearchIndexResponse)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/searchIndices.watch

The equivalent REST API is:

POST /v1/{name=searchDbs/*/searchIndices/*}:watch 

POST /v1/{name=projects/*/searchDbs/*/searchIndices/*}:watch

WatchSearchIndices Method

WatchSearchIndices

rpc WatchSearchIndices(WatchSearchIndicesRequest) returns (WatchSearchIndicesResponse)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/searchIndices.watch

The equivalent REST API is:

POST /v1/{parent=searchDbs/*}/searchIndices:watch 

POST /v1/{parent=projects/*/searchDbs/*}/searchIndices:watch

CreateSearchIndex Method

CreateSearchIndex

rpc CreateSearchIndex(CreateSearchIndexRequest) returns (SearchIndex)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/searchIndices.create

The equivalent REST API is:

POST /v1/{parent=searchDbs/*}/searchIndices (BODY: search_index)

POST /v1/{parent=projects/*/searchDbs/*}/searchIndices

UpdateSearchIndex Method

UpdateSearchIndex

rpc UpdateSearchIndex(UpdateSearchIndexRequest) returns (SearchIndex)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/searchIndices.update

The equivalent REST API is:

PUT /v1/{search_index.name=searchDbs/*/searchIndices/*} (BODY: search_index)

PUT /v1/{search_index.name=projects/*/searchDbs/*/searchIndices/*}

DeleteSearchIndex Method

DeleteSearchIndex

rpc DeleteSearchIndex(DeleteSearchIndexRequest) returns (Empty)

with the following messages:

Required Permissions:

  • services/ai.edgelq.com/permissions/searchIndices.delete

The equivalent REST API is:

DELETE /v1/{name=searchDbs/*/searchIndices/*} 

DELETE /v1/{name=projects/*/searchDbs/*/searchIndices/*}

SearchIndex Messages

Here is the list of SearchIndex resource messages:

SearchIndex Message

Name Type Description
name string (name of SearchIndex) Name of SearchIndex When creating a new instance, this field is optional and if not provided, it will be generated automatically. Last ID segment must conform to the following regex: [a-z][a-z0-9\-]{0,28}[a-z0-9]
metadata Meta Metadata is an object with information like create, update and delete time (for async deleted resources), has user labels/annotations, sharding information, multi-region syncing information and may have non-schema owners (useful for taking ownership of resources belonging to lower level services by higher ones).
index_name string
display_name string Human-readable display name for this search index
description string Description of what content this index contains
tokens_per_chunk int32
overlap_tokens int32

GetSearchIndexRequest Message

A request message of the GetSearchIndex method.

Name Type Description
name string (name of SearchIndex) Name of ntt.ai.v1.SearchIndex
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetSearchIndicesRequest Message

A request message of the BatchGetSearchIndices method.

Name Type Description
names repeated string (name of SearchIndex) Names of SearchIndices
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetSearchIndicesResponse Message

A response message of the BatchGetSearchIndices method.

Name Type Description
search_indices repeated SearchIndex found SearchIndices
missing repeated string (name of SearchIndex) list of not found SearchIndices

ListSearchIndicesRequest Message

A request message of the ListSearchIndices method.

Name Type Description
parent string (parent name of SearchIndex) Parent name of ntt.ai.v1.SearchIndex
page_size int32 Requested page size. Server may return fewer SearchIndices than requested. If unspecified, server will pick an appropriate default.
page_token string (cursor of SearchIndex) A token identifying a page of results the server should return. Typically, this is the value of ListSearchIndicesResponse.next_page_token.
order_by string (orderBy of SearchIndex) Order By - https://cloud.google.com/apis/design/design_patterns#list_pagination list of field path with order directive, either ‘asc’ or ‘desc’. If direction is not provided, ‘asc’ is assumed. e.g. “state.nested_field asc, state.something.else desc, theme”
filter string (filter of SearchIndex) Filter - filter results by field criteria. Simplified SQL-like syntax with following operators: <=, >=, =, !=, <, >, LIKE, CONTAINS (aliases CONTAIN, HAS, HAVE), IN, IS [NOT] NULL
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask
include_paging_info bool Indicates if list response should contain total count and offset (fields current_offset and total_results_count).

ListSearchIndicesResponse Message

A response message of the ListSearchIndices method.

Name Type Description
search_indices repeated SearchIndex The list of SearchIndices
prev_page_token string (cursor of SearchIndex) A token to retrieve previous page of results. Pass this value in the ListSearchIndicesRequest.page_token.
next_page_token string (cursor of SearchIndex) A token to retrieve next page of results. Pass this value in the ListSearchIndicesRequest.page_token.
current_offset int32 Current offset from the first page or 0 if no page tokens were given, paging info was not requested or there was an error while trying to get it). Page index can be computed from offset and limit provided in a request.
total_results_count int32 Number of total SearchIndices across all pages or 0, if there are no items, paging info was not requested or there was an error while trying to get it.

WatchSearchIndexRequest Message

A request message of the WatchSearchIndex method.

Name Type Description
name string (name of SearchIndex) Name of ntt.ai.v1.SearchIndex
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

WatchSearchIndexResponse Message

A response message of the WatchSearchIndex method.

Name Type Description
change SearchIndexChange

WatchSearchIndicesRequest Message

A request message of the WatchSearchIndices method.

Name Type Description
type WatchType Type of a watch. Identifies how server stream data to a client, which fields in a request are allowed and which fields in response are relevant.
parent string (parent name of SearchIndex) Parent name of ntt.ai.v1.SearchIndex
page_size int32 Requested page size. Server may return fewer SearchIndices than requested. If unspecified, server will pick an appropriate default. Can be populated only for stateful watch type.
page_token string (cursor of SearchIndex) A token identifying a page of results the server should return. Can be populated only for stateful watch type.
order_by string (orderBy of SearchIndex) Order By - https://cloud.google.com/apis/design/design_patterns#list_pagination Can be populated only for stateful watch type.
resume_token string A token identifying watch resume point from previous session. Can be populated only for stateless watch type.
starting_time .google.protobuf.Timestamp Point in the time from which we want to start getting updates. This field can be populated only for stateless watch type and if resume token is not known yet. If specified, initial snapshot will NOT be provided. It is assumed client can obtain it using separate means. Watch responses will contain resume tokens which should be used to resume broken connection.
filter string (filter of SearchIndex) Filter - filter results by field criteria. Simplified SQL-like syntax with following operators: <=, >=, =, !=, <, >, LIKE, CONTAINS (aliases CONTAIN, HAS, HAVE), IN, IS [NOT] NULL
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view Changes to SearchIndex that don’t affect any of masked fields won’t be sent back.
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask Changes to SearchIndex that don’t affect any of masked fields won’t be sent back.
max_chunk_size int32 Maximum amount of changes in each response message. Query result response is divided on the server side into chunks with size of a specified amount to limit memory footprint of each message. Responses will hold information whether more elements will continue for the actual change. If unspecified, server will pick an appropriate default.

WatchSearchIndicesResponse Message

A response message of the WatchSearchIndices method.

Name Type Description
search_index_changes repeated SearchIndexChange Changes of SearchIndices
is_current bool If request specified max_chunk_size (or this limit was enforced if stateless watch has been chosen), then responses with “full changeset” will be divided into chunks. Client should keep receiving messages and, once is_current has value true, combine this recent message with all previous ones where is_current is false. If this is the first is_current in a whole watch stream, then it means that client should have, at this moment, contain snapshot of the current situation (or more accurately, snapshot of situation at the moment of request). All SearchIndices will be of type Added/Current (depending on watch_type specified in the request). Further responses will be incremental - however messages may still be chunked and is_current logic still applies. is_current is always true for stateful watch if max_chunk_size was left to 0.
page_token_change WatchSearchIndicesResponse.PageTokenChange When present, PageTokens used for page navigation should be updated. Present only if is_current is true (last chunk).
resume_token string Token that can be used if current connection drops and client needs to reconnect. Populated only for stateless watch type. Present only if is_current is true (last chunk).
snapshot_size int64 Server may occasionally send information how many resources should client have in its state so far (response message without any changes, but with snapshot_size field specified). If client has different value than the one sent by the server, then it should be treated by a client as an error and should reconnect. If value is smaller then 0, then client should ignore this field as unpopulated. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will be never sent together with is_current, is_soft_reset and is_hard_reset flags.
is_soft_reset bool In case of internal issue server may send response message with this flag. It indicates that client should drop all changes from recent responses where is_current is false only! If last message had is_current set to true, client should do nothing and process normally. Resume token received before is still valid. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will never be sent along with is_current, is_hard_reset or snapshot_size.
is_hard_reset bool In case of internal issue server may send response message with this flag. After receiving, client should clear whole state (drop all changes received so far) as server will send new snapshot (SearchIndices will contains changes of type Current only). Any resume tokens should be discarded as well. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will never be sent along with is_current, is_soft_reset or snapshot_size.

WatchSearchIndicesResponse.PageTokenChange Message

Name Type Description
prev_page_token string (cursor of SearchIndex) New token to retrieve previous page of results.
next_page_token string (cursor of SearchIndex) New token to retrieve next page of results.

CreateSearchIndexRequest Message

A request message of the CreateSearchIndex method.

Name Type Description
parent string (parent name of SearchIndex) Parent name of ntt.ai.v1.SearchIndex
search_index SearchIndex SearchIndex resource body
response_mask CreateSearchIndexRequest.ResponseMask Optional masking applied to response object to reduce message response size.

CreateSearchIndexRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

Name Type Description
skip_entire_response_body bool If this flag has value true, then response will contain just empty resource without any fields populated.
body_mask .google.protobuf.FieldMask If this field is populated, then resource in response will contain only specific fields.

UpdateSearchIndexRequest Message

A request message of the UpdateSearchIndex method.

Name Type Description
search_index SearchIndex SearchIndex resource body
update_mask .google.protobuf.FieldMask FieldMask applied to request - change will be applied only for fields in the mask
cas UpdateSearchIndexRequest.CAS Conditional update applied to request if update should be executed only for specific resource state. If this field is populated, then server will fetch existing resource, compare with the one stored in the cas field (after applying field mask) and proceed with update only and only if they match. Otherwise RPC error Aborted will be returned.
allow_missing bool If set to true, and the resource is not found, a new resource will be created. In this situation, ‘field_mask’ is ignored. https://google.aip.dev/134#create-or-update
response_mask UpdateSearchIndexRequest.ResponseMask reduce message response size.

UpdateSearchIndexRequest.CAS Message

CAS - Compare and Swap. This object is used if user wants to make update conditional based upon previous resource version.

Name Type Description
conditional_state SearchIndex Conditional desired state of a resource before update.
field_mask .google.protobuf.FieldMask Field paths from conditional state of resource server should check and compare.

UpdateSearchIndexRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

Name Type Description
skip_entire_response_body bool If this flag has value true, then response will contain just empty resource without any fields populated. Field body_mask is ignored if set.
updated_fields_only bool Include all fields that were actually updated during processing. Note this may be larger than update mask if some fields were computed additionally. Name is added as well.
body_mask .google.protobuf.FieldMask If this field is populated, then resource in response will contain only specific fields. If skip_entire_response_body is true, this field is ignored.

DeleteSearchIndexRequest Message

A request message of the DeleteSearchIndex method.

Name Type Description
name string (name of SearchIndex) Name of ntt.ai.v1.SearchIndex
allow_missing bool If set to true, and the resource is not found, method will be successful and will not return NotFound error.

AI Service Shared Methods and Messages

AI Service Shared Methods

Here is the list of AI service shared methods:

Completion Method

Completion

rpc Completion(CompletionRequest) returns (CompletionResponse)

CreateResponse Method

CreateResponse

rpc CreateResponse(CreateResponseRequest) returns (CreateResponseResult)

ChatStream Method

ChatStream

rpc ChatStream(ChatStreamRequest) returns (ChatStreamResponse)

ExecuteTools Method

ExecuteTools

rpc ExecuteTools(ExecuteToolsRequest) returns (ExecuteToolsResponse)

AI Service Shared Messages

Here is the list of AI service shared messages:

AnthropicConfig Message

Name Type Description
thinking ThinkingConfig Extended thinking configuration
beta_features repeated string Beta features to enable (e.g., [“prompt-caching-2024-07-31”, “pdfs-2024-09-25”])
disable_input_token_cache bool When true, disables prompt caching

AudioContent Message

Name Type Description
url string
data bytes
mime_type string

AzureConfig Message

Name Type Description
search AzureSearchConfig
parallel_tool_calls bool
max_completion_tokens int32
reasoning_effort string

AzureSearchConfig Message

Name Type Description
endpoint string
index string
api_key string
enable_semantic bool

BlockEnd Message

Block end signal - indicates a content or thinking block has completed

Name Type Description
channel ContentChannel
signature string

CancelOauth Message

Allows the client to cancel an in-flight OAuth attempt.

Name Type Description
login_id string login_id returned in the Redirect event to correlate cancellation.

CapabilityTemplateChange Message

CapabilityTemplateChange is used by Watch notifications Responses to describe change of single CapabilityTemplate One of Added, Modified, Removed

Name Type Description
added CapabilityTemplateChange.Added Added is returned when watched document is added, either created or enters Query view
modified CapabilityTemplateChange.Modified Modified is returned when watched document is modified
current CapabilityTemplateChange.Current Current is returned in stateless watch when document enters query view or is modified within.
removed CapabilityTemplateChange.Removed Removed is returned when CapabilityTemplate is deleted or leaves Query view

CapabilityTemplateChange.Added Message

CapabilityTemplate has been added to query view

Name Type Description
capability_template CapabilityTemplate
view_index int32 Integer describing index of added CapabilityTemplate in resulting query view.

CapabilityTemplateChange.Current Message

CapabilityTemplate has been added or modified in a query view. Version used for stateless watching

Name Type Description
capability_template CapabilityTemplate

CapabilityTemplateChange.Modified Message

CapabilityTemplate changed some of it’s fields - contains either full document or masked change

Name Type Description
name string (name of CapabilityTemplate) Name of modified CapabilityTemplate
capability_template CapabilityTemplate New version of CapabilityTemplate or masked difference, depending on mask_changes instrumentation of issued [WatchCapabilityTemplateRequest] or [WatchCapabilityTemplatesRequest]
field_mask .google.protobuf.FieldMask Used when mask_changes is set, contains field paths of modified properties.
previous_view_index int32 Previous view index specifies previous position of modified CapabilityTemplate. When modification doesn’t affect sorted order, value will remain identical to [view_index].
view_index int32 Integer specifying CapabilityTemplate new index in resulting query view.

CapabilityTemplateChange.Removed Message

Removed is returned when CapabilityTemplate is deleted or leaves Query view

Name Type Description
name string (name of CapabilityTemplate)
view_index int32 Integer specifying removed CapabilityTemplate index. Not populated in stateless watch type.

CharacterRange Message

Character range in source document

Name Type Description
start int64
end int64

ChatInput Message

Full-transcript input per turn with optional overrides

Name Type Description
messages repeated Message
overrides InputOverrides
resume ResumeConfig Stateful only: resume/edit operation. Incompatible with messages.

ChatModelChange Message

ChatModelChange is used by Watch notifications Responses to describe change of single ChatModel One of Added, Modified, Removed

Name Type Description
added ChatModelChange.Added Added is returned when watched document is added, either created or enters Query view
modified ChatModelChange.Modified Modified is returned when watched document is modified
current ChatModelChange.Current Current is returned in stateless watch when document enters query view or is modified within.
removed ChatModelChange.Removed Removed is returned when ChatModel is deleted or leaves Query view

ChatModelChange.Added Message

ChatModel has been added to query view

Name Type Description
chat_model ChatModel
view_index int32 Integer describing index of added ChatModel in resulting query view.

ChatModelChange.Current Message

ChatModel has been added or modified in a query view. Version used for stateless watching

Name Type Description
chat_model ChatModel

ChatModelChange.Modified Message

ChatModel changed some of it’s fields - contains either full document or masked change

Name Type Description
name string (name of ChatModel) Name of modified ChatModel
chat_model ChatModel New version of ChatModel or masked difference, depending on mask_changes instrumentation of issued [WatchChatModelRequest] or [WatchChatModelsRequest]
field_mask .google.protobuf.FieldMask Used when mask_changes is set, contains field paths of modified properties.
previous_view_index int32 Previous view index specifies previous position of modified ChatModel. When modification doesn’t affect sorted order, value will remain identical to [view_index].
view_index int32 Integer specifying ChatModel new index in resulting query view.

ChatModelChange.Removed Message

Removed is returned when ChatModel is deleted or leaves Query view

Name Type Description
name string (name of ChatModel)
view_index int32 Integer specifying removed ChatModel index. Not populated in stateless watch type.

ChatParameters Message

Provider-specific parameters

Name Type Description
max_tokens int32 Maximum tokens to generate
temperature float Temperature (0.0 - 2.0)
top_p float Top-p nucleus sampling
top_k int32 Top-k sampling (Anthropic, Gemini)
presence_penalty float Presence penalty (OpenAI)
frequency_penalty float Frequency penalty (OpenAI)
seed int64
stop_sequences repeated string
response_format ResponseFormat Response format
logprobs bool Whether to return log probabilities
top_logprobs int32 Number of most likely tokens to return

ChatStreamRequest Message

Client → Server messages for ChatStream

Name Type Description
init InitializeSession
input ChatInput

ChatStreamResponse Message

Server → Client messages for ChatStream

Name Type Description
session_initialized SessionInitialized Session initialization complete
response_started ResponseStarted Reuse all existing event types from CreateResponseResult
content_delta ContentDelta
content_done ContentDone
thinking_delta ThinkingDelta
thinking_done ThinkingDone
tool_calls ToolCalls
response_complete ResponseComplete
error Error
citation_delta CitationDelta

Citation Message

Citation - reference to source material (provider-agnostic)

Name Type Description
start_index int64 Text reference in AI response (which part is cited)
end_index int64
text string
source CitationSource Source information

CitationDelta Message

Name Type Description
citation Citation Citation from common.proto

CitationSource Message

Citation source information

Name Type Description
title string Core fields (all providers)
id string
quoted_text string
char_range CharacterRange
page PageReference
url URLReference
metadata map<string, string> Generic metadata (extensible for any provider-specific data)

ClientToolSource Message

Tool source types (shared across chat and conversation persistence) Client tool - executed by client locally

Name Type Description
none none none

CompletionRequest Message

A request message of the Completion method.

Name Type Description
init CompletionRequest.Init
query Msg

CompletionRequest.Init Message

Name Type Description
chat_model string (name of ChatModel)
search_index string (name of SearchIndex)
history repeated Msg

CompletionResponse Message

A response message of the Completion method.

Name Type Description
response Msg
complete bool

ConnectorAuthError Message

Per-connector auth failure for the current user in a single API call.

Name Type Description
connector string Full connector resource name, e.g. “connectors/projects/…/connectorId”
code ConnectorAuthErrorCode

ConnectorChange Message

ConnectorChange is used by Watch notifications Responses to describe change of single Connector One of Added, Modified, Removed

Name Type Description
added ConnectorChange.Added Added is returned when watched document is added, either created or enters Query view
modified ConnectorChange.Modified Modified is returned when watched document is modified
current ConnectorChange.Current Current is returned in stateless watch when document enters query view or is modified within.
removed ConnectorChange.Removed Removed is returned when Connector is deleted or leaves Query view

ConnectorChange.Added Message

Connector has been added to query view

Name Type Description
connector Connector
view_index int32 Integer describing index of added Connector in resulting query view.

ConnectorChange.Current Message

Connector has been added or modified in a query view. Version used for stateless watching

Name Type Description
connector Connector

ConnectorChange.Modified Message

Connector changed some of it’s fields - contains either full document or masked change

Name Type Description
name string (name of Connector) Name of modified Connector
connector Connector New version of Connector or masked difference, depending on mask_changes instrumentation of issued [WatchConnectorRequest] or [WatchConnectorsRequest]
field_mask .google.protobuf.FieldMask Used when mask_changes is set, contains field paths of modified properties.
previous_view_index int32 Previous view index specifies previous position of modified Connector. When modification doesn’t affect sorted order, value will remain identical to [view_index].
view_index int32 Integer specifying Connector new index in resulting query view.

ConnectorChange.Removed Message

Removed is returned when Connector is deleted or leaves Query view

Name Type Description
name string (name of Connector)
view_index int32 Integer specifying removed Connector index. Not populated in stateless watch type.

ConnectorToolSource Message

Connector tool - executed via MCP/other connector

Name Type Description
connector_name string (name of Connector)

ConnectorUserTokenChange Message

ConnectorUserTokenChange is used by Watch notifications Responses to describe change of single ConnectorUserToken One of Added, Modified, Removed

Name Type Description
added ConnectorUserTokenChange.Added Added is returned when watched document is added, either created or enters Query view
modified ConnectorUserTokenChange.Modified Modified is returned when watched document is modified
current ConnectorUserTokenChange.Current Current is returned in stateless watch when document enters query view or is modified within.
removed ConnectorUserTokenChange.Removed Removed is returned when ConnectorUserToken is deleted or leaves Query view

ConnectorUserTokenChange.Added Message

ConnectorUserToken has been added to query view

Name Type Description
connector_user_token ConnectorUserToken
view_index int32 Integer describing index of added ConnectorUserToken in resulting query view.

ConnectorUserTokenChange.Current Message

ConnectorUserToken has been added or modified in a query view. Version used for stateless watching

Name Type Description
connector_user_token ConnectorUserToken

ConnectorUserTokenChange.Modified Message

ConnectorUserToken changed some of it’s fields - contains either full document or masked change

Name Type Description
name string (name of ConnectorUserToken) Name of modified ConnectorUserToken
connector_user_token ConnectorUserToken New version of ConnectorUserToken or masked difference, depending on mask_changes instrumentation of issued [WatchConnectorUserTokenRequest] or [WatchConnectorUserTokensRequest]
field_mask .google.protobuf.FieldMask Used when mask_changes is set, contains field paths of modified properties.
previous_view_index int32 Previous view index specifies previous position of modified ConnectorUserToken. When modification doesn’t affect sorted order, value will remain identical to [view_index].
view_index int32 Integer specifying ConnectorUserToken new index in resulting query view.

ConnectorUserTokenChange.Removed Message

Removed is returned when ConnectorUserToken is deleted or leaves Query view

Name Type Description
name string (name of ConnectorUserToken)
view_index int32 Integer specifying removed ConnectorUserToken index. Not populated in stateless watch type.

ConnectorUserTokenSecret Message

Secret payload maintained by the server - not returned to clients.

Name Type Description
ciphertext bytes Ciphertext returned from the configured encrypter backend.
encryption_key_name string Name of the crypto key used to encrypt/decrypt the payload.
payload_version string Version marker for the serialized payload stored in ciphertext.
updated_at .google.protobuf.Timestamp Timestamp when the secret payload was last updated.

ConnectorsList Message

List of connectors for direct specification

Name Type Description
connector repeated string (name of Connector)

ContentDelta Message

Name Type Description
text string

ContentDone Message

Name Type Description
text string

ContentPart Message

Multimodal content part

Name Type Description
text TextContent
image ImageContent
audio AudioContent
file FileContent
tool_call ToolCall
tool_result ToolResponse
thinking ThinkingContent

ConversationChange Message

ConversationChange is used by Watch notifications Responses to describe change of single Conversation One of Added, Modified, Removed

Name Type Description
added ConversationChange.Added Added is returned when watched document is added, either created or enters Query view
modified ConversationChange.Modified Modified is returned when watched document is modified
current ConversationChange.Current Current is returned in stateless watch when document enters query view or is modified within.
removed ConversationChange.Removed Removed is returned when Conversation is deleted or leaves Query view

ConversationChange.Added Message

Conversation has been added to query view

Name Type Description
conversation Conversation
view_index int32 Integer describing index of added Conversation in resulting query view.

ConversationChange.Current Message

Conversation has been added or modified in a query view. Version used for stateless watching

Name Type Description
conversation Conversation

ConversationChange.Modified Message

Conversation changed some of it’s fields - contains either full document or masked change

Name Type Description
name string (name of Conversation) Name of modified Conversation
conversation Conversation New version of Conversation or masked difference, depending on mask_changes instrumentation of issued [WatchConversationRequest] or [WatchConversationsRequest]
field_mask .google.protobuf.FieldMask Used when mask_changes is set, contains field paths of modified properties.
previous_view_index int32 Previous view index specifies previous position of modified Conversation. When modification doesn’t affect sorted order, value will remain identical to [view_index].
view_index int32 Integer specifying Conversation new index in resulting query view.

ConversationChange.Removed Message

Removed is returned when Conversation is deleted or leaves Query view

Name Type Description
name string (name of Conversation)
view_index int32 Integer specifying removed Conversation index. Not populated in stateless watch type.

ConversationFeedbackChange Message

ConversationFeedbackChange is used by Watch notifications Responses to describe change of single ConversationFeedback One of Added, Modified, Removed

Name Type Description
added ConversationFeedbackChange.Added Added is returned when watched document is added, either created or enters Query view
modified ConversationFeedbackChange.Modified Modified is returned when watched document is modified
current ConversationFeedbackChange.Current Current is returned in stateless watch when document enters query view or is modified within.
removed ConversationFeedbackChange.Removed Removed is returned when ConversationFeedback is deleted or leaves Query view

ConversationFeedbackChange.Added Message

ConversationFeedback has been added to query view

Name Type Description
conversation_feedback ConversationFeedback
view_index int32 Integer describing index of added ConversationFeedback in resulting query view.

ConversationFeedbackChange.Current Message

ConversationFeedback has been added or modified in a query view. Version used for stateless watching

Name Type Description
conversation_feedback ConversationFeedback

ConversationFeedbackChange.Modified Message

ConversationFeedback changed some of it’s fields - contains either full document or masked change

Name Type Description
name string (name of ConversationFeedback) Name of modified ConversationFeedback
conversation_feedback ConversationFeedback New version of ConversationFeedback or masked difference, depending on mask_changes instrumentation of issued [WatchConversationFeedbackRequest] or [WatchConversationFeedbacksRequest]
field_mask .google.protobuf.FieldMask Used when mask_changes is set, contains field paths of modified properties.
previous_view_index int32 Previous view index specifies previous position of modified ConversationFeedback. When modification doesn’t affect sorted order, value will remain identical to [view_index].
view_index int32 Integer specifying ConversationFeedback new index in resulting query view.

ConversationFeedbackChange.Removed Message

Removed is returned when ConversationFeedback is deleted or leaves Query view

Name Type Description
name string (name of ConversationFeedback)
view_index int32 Integer specifying removed ConversationFeedback index. Not populated in stateless watch type.

ConversationTurn Message

Represents one CreateResponse API call

Name Type Description
turn_number int32 Sequential turn number (0-indexed)
timestamp .google.protobuf.Timestamp When this turn started
messages repeated Message Messages added in THIS turn only (not full history) Typically: [user_msg, assistant_msg] or [tool_result_msg, assistant_msg]
config TurnConfig Configuration used for this specific API call
usage TokenUsage Token usage for this specific turn
stop_reason StopReason How this turn ended
duration .google.protobuf.Duration Duration of the API call
available_tools_by_source repeated TurnToolsBySourceGroup Tools grouped by source (authoritative for resume)
replaced_turn_number int32 If this turn replaced a previous turn (from resume operation) Points to the turn number that was replaced
error_details string Error details if stop_reason is ERROR

CreateRequest Message

Name Type Description
messages repeated Message The conversation
model string (name of ChatModel) Model selection
client_tools repeated ToolDefinition Client explicitly declares its tools
capability_template string (name of CapabilityTemplate) Option 1: Use a pre-configured capability template
connectors ConnectorsList Option 2: Directly specify connectors
max_tokens int32 Standard LLM params
temperature float
conversation_name string (name of Conversation) Optional: reference to existing conversation
parent string Scope for authorization and tracking. Can be project, organization, or empty. Format: “projects/{project}”, “organizations/{org}”, or ""
reasoning_level ReasoningLevel Requested reasoning level (optional, capped by template max)
disable_input_token_cache bool Override to disable Anthropic prompt caching for this request
prompt_variables map<string, string> Optional prompt variables passed by the client for template rendering Used by capability templates’ system_prompt_append when variables use request_key source Server applies automatic sanitization: - Max 8KB per value, 64KB total - Control characters stripped (except \n and \t) - Values are treated as untrusted user input
resume_config ResumeConfig Resume configuration for editing conversation history When set, resumes conversation from a specific turn Requires conversation_name to be set Incompatible with direct messages array
skip_tool_discovery bool When true, skips server-side tool discovery from connectors and templates. The capability template is still loaded for system prompt, model config, reasoning settings, etc. — only tool discovery is skipped. Useful for one-shot request/response flows that don’t need tool calls.
response_format ResponseFormat Response format constraint (e.g., JSON output)

CreateResponseRequest Message

Client → Server messages

Name Type Description
create_request CreateRequest

CreateResponseResult Message

Server → Client messages

Name Type Description
response_started ResponseStarted
content_delta ContentDelta
content_done ContentDone
thinking_delta ThinkingDelta
thinking_done ThinkingDone
tool_calls ToolCalls
response_complete ResponseComplete
error Error
citation_delta CitationDelta

DocumentChange Message

DocumentChange is used by Watch notifications Responses to describe change of single Document One of Added, Modified, Removed

Name Type Description
added DocumentChange.Added Added is returned when watched document is added, either created or enters Query view
modified DocumentChange.Modified Modified is returned when watched document is modified
current DocumentChange.Current Current is returned in stateless watch when document enters query view or is modified within.
removed DocumentChange.Removed Removed is returned when Document is deleted or leaves Query view

DocumentChange.Added Message

Document has been added to query view

Name Type Description
document Document
view_index int32 Integer describing index of added Document in resulting query view.

DocumentChange.Current Message

Document has been added or modified in a query view. Version used for stateless watching

Name Type Description
document Document

DocumentChange.Modified Message

Document changed some of it’s fields - contains either full document or masked change

Name Type Description
name string (name of Document) Name of modified Document
document Document New version of Document or masked difference, depending on mask_changes instrumentation of issued [WatchDocumentRequest] or [WatchDocumentsRequest]
field_mask .google.protobuf.FieldMask Used when mask_changes is set, contains field paths of modified properties.
previous_view_index int32 Previous view index specifies previous position of modified Document. When modification doesn’t affect sorted order, value will remain identical to [view_index].
view_index int32 Integer specifying Document new index in resulting query view.

DocumentChange.Removed Message

Removed is returned when Document is deleted or leaves Query view

Name Type Description
name string (name of Document)
view_index int32 Integer specifying removed Document index. Not populated in stateless watch type.

Error Message

Name Type Description
code string
message string
connector_auth_errors repeated ConnectorAuthError Connector authentication errors that blocked this request for the current user. Empty for non-connector-related failures.

ExecuteToolsRequest Message

A request message of the ExecuteTools method.

Name Type Description
tool_executions repeated ToolExecution
client_request_id string Client-provided request ID for idempotency and log correlation
parent string Scope for authorization and tracking. Can be project, organization, or empty. Format: “projects/{project}”, “organizations/{org}”, or ""

ExecuteToolsResponse Message

A response message of the ExecuteTools method.

Name Type Description
results repeated ToolExecutionResult

FileContent Message

Name Type Description
name string
mime_type string
url string
data bytes

GeminiConfig Message

Name Type Description
none none none

GenerationParameters Message

Grouped generation parameters

Name Type Description
max_tokens int32
temperature float
reasoning_level ReasoningLevel
disable_input_token_cache .google.protobuf.BoolValue
response_format ResponseFormat Response format constraint (e.g., JSON output)

ImageContent Message

Name Type Description
url string
data bytes
mime_type string

IndexingPolicy Message

Name Type Description
chunk_size_tokens uint32s
chunk_overlap_tokens uint32s
embedding_model string
chunking_strategy string

InitializeSession Message

Heavy initialization message - sent once at session start

Name Type Description
model string (name of ChatModel) Model selection
capability_template string (name of CapabilityTemplate) Required capability template for ChatStream (connectors not supported here)
client_tools repeated ToolDefinition Optional: Client declared tools
parameters GenerationParameters Default generation parameters
prompt_variables map<string, string> Default prompt variables for template rendering
conversation_name string (name of Conversation) Optional: bind to existing conversation (stateful mode)
parent string Scope for authorization and tracking. Can be project, organization, or empty.

InputOverrides Message

Per-input overrides grouped for clarity

Name Type Description
parameters GenerationParameters
client_tools repeated ToolDefinition
prompt_variables map<string, string>
model string (name of ChatModel)

InputTokenBreakdown Message

Universal input token breakdown (all providers map here)

Name Type Description
fresh_input int32
cached_input int32
cache_write_five_min int32
cache_write_one_hour int32
audio_input int32
tool_use_input int32

InternalToolSource Message

Internal server tool (e.g., RAG)

Name Type Description
type InternalToolSource.Type
template_name string Capability Template name for internal tools Server knows how to extract the right config from the template

MCPConfig Message

MCP-specific configuration

Name Type Description
endpoint string Connection endpoint (transport determined by scheme) - stdio://command - Local process, no auth - http(s)://host/path - HTTP/HTTPS, OAuth required - sse://host/path - SSE, OAuth required
args repeated string Command arguments (only for stdio:// transport)
environment map<string, string> Environment variables (only for stdio:// transport)

Message Message

Message structure for conversations

Name Type Description
role string
parts repeated ContentPart

ModelCapabilities Message

Model capabilities information

Name Type Description
context_window int32
max_output_tokens int32
supports_tools bool
supports_thinking bool
supported_modalities repeated string

ModelUsageStats Message

Per-model usage statistics

Name Type Description
turn_count int32
aggregated_usage TokenUsage Aggregated token usage for this model (sum of all turns)

Msg Message

Name Type Description
content string
type Msg.Type

OAuthConfig Message

OAuth configuration for a connector. This is the effective configuration used by the service, regardless of whether fields were provided statically by the user or auto-populated from discovery / DCR / CIMD.

Name Type Description
client_id string Pre-registered OAuth client ID (or URL for CIMD).
client_secret string Reference to secret containing client secret (for confidential clients).
authorization_endpoint string Effective authorization endpoint.
token_endpoint string Effective token endpoint.
additional_scopes repeated string Additional scopes beyond what MCP server declares.
issuer string Issuer for this configuration (from discovery or static config).
resource_url string Resource URL used for discovery (typically the MCP protected resource origin).
resource_param string Effective resource parameter to send in auth/token/PAR requests.
par_endpoint string Pushed Authorization Request endpoint, if available.
token_endpoint_auth_methods repeated string Token endpoint authentication methods supported by this AS.
preferred_token_endpoint_auth_method string Preferred token endpoint auth method for this client (from CIMD or DCR), if any.
scopes_supported repeated string Supported scopes advertised by the AS.
dpop_signing_algs repeated string Supported DPoP signing algorithms.
downstream_consent_scopes repeated string Optional downstream consent scopes that require a separate consent flow after the primary connector token has been obtained. These are typically provider-specific resource scopes (for example, “https://kusto.kusto.windows.net/.default") that cannot be mixed with the main connector API scopes.
auto_populated bool True if this configuration was auto-populated (fully or partially) by the backend (discovery, DCR, CIMD). When false, fields are presumed user-specified.
auto_populated_at int64 Unix timestamp (seconds) of last successful auto-population.
auto_source string Source of auto-population (e.g., “discovery”, “discovery+dcr”, “discovery+cimd”).

OauthCompletion Message

Final completion event once the callback finishes (success, timeout, etc.).

Name Type Description
login_id string
status OauthCompletion.Status
message string Optional human readable message (e.g., error details).
user_email string Populated on success to describe the linked user identity.
display_name string
avatar_url string

OauthError Message

Error event when the backend fails to initiate the handshake.

Name Type Description
login_id string
code string
message string

OauthKeepAlive Message

Periodic server-side keep-alive to reassure the client the stream is active.

Name Type Description
none none none

OauthPing Message

Lightweight keep-alive to keep the stream open through long-running logins.

Name Type Description
none none none

OauthRedirect Message

Server response instructing the client to redirect the browser.

Name Type Description
login_id string Opaque identifier correlating this login attempt.
authorization_url string Where the SPA should redirect the browser to continue the flow.
expires_at_epoch int64 Expiration timestamp (seconds since epoch) for this login attempt.

OpenAIConfig Message

Provider-specific configurations

Name Type Description
parallel_tool_calls bool
max_completion_tokens int32
reasoning_effort string

OutputTokenBreakdown Message

Universal output token breakdown (all providers map here)

Name Type Description
regular_output int32
reasoning_output int32
audio_output int32

PageReference Message

Page reference in source document

Name Type Description
page_number int32

Payload Message

Payload for data with media type

Name Type Description
json string
data bytes
media_type string

PromptAppendTemplate Message

Templated append to the system prompt using Go template syntax ({{.var}}) The server always renders templates - clients supply variable values via CreateRequest.prompt_variables

  • Server applies automatic sanitization (8000 chars per value, 64000 chars total, control chars stripped)

Example (server variables - auto-detected): text: “User: {{.userEmail}}, Project: {{.projectName}}” mode: MODE_SERVER on_missing: PROMPT_MISSING_VAR_POLICY_ERROR

Example (client variables with optional sections): text: “Task: {{.task}}{{if .priority}}, Priority: {{.priority}}{{end}}” mode: MODE_CLIENT on_missing: PROMPT_MISSING_VAR_POLICY_SKIP_APPEND // Variables automatically detected: task, priority // Use {{if}} for optional sections instead of defaults

Name Type Description
text string
mode PromptVariableMode
on_missing PromptMissingVarPolicy

ProviderChatRequest Message

Provider chat request

Name Type Description
model string Model name or deployment ID
messages repeated Message Conversation messages
tools repeated ToolDefinition Available tools
parameters ChatParameters Generation parameters
user string User identifier for abuse tracking
metadata map<string, string> Request metadata (request ID, tracing, etc.)
openai_config OpenAIConfig
azure_config AzureConfig
anthropic_config AnthropicConfig
gemini_config GeminiConfig
reasoning_level ReasoningLevel Provider-agnostic reasoning level

ProviderContentDelta Message

Provider content delta for streaming

Name Type Description
text string
channel ContentChannel

ProviderDone Message

Stream completion event

Name Type Description
stop_reason ProviderDone.StopReason

ProviderStreamEvent Message

Provider streaming event

Name Type Description
delta ProviderContentDelta
usage TokenUsage
error StreamError
done ProviderDone
tool_calls ToolCalls
citation Citation
block_end BlockEnd

RAGConfig Message

RAG (Retrieval-Augmented Generation) configuration

Name Type Description
search_indices repeated string (reference to SearchIndex) Search indices available for RAG tool to search
indexing_policy IndexingPolicy Indexing configuration
retrieval_limits RetrievalLimits Retrieval limits
use_azure_native_rag bool When true and using Azure OpenAI models, use Azure’s native “On Your Data” extensions instead of tool-based RAG. When false, RAG is exposed as “internal.rag.search” tool.

ReasoningConfig Message

Reasoning configuration for AI models

Name Type Description
max_level ReasoningLevel Maximum allowed reasoning level for requests using this template
default_level ReasoningLevel Default level if not specified in request

ReplacedTurnGroup Message

Group of turns replaced during a single resume operation

Name Type Description
replaced_at .google.protobuf.Timestamp When this resume operation happened
resumed_from_turn int32 Which turn the conversation was resumed from (0-indexed)
turns repeated ConversationTurn The turns that were replaced/discarded in this operation Ordered by turn_number
had_message_edit bool Whether the message was edited when resuming (applies to user or tool messages)
resume_reason string Optional: User comment/reason for the resume

ResponseComplete Message

Name Type Description
requires_tool_results bool
stop_reason StopReason
usage TokenUsage
cumulative_usage TokenUsage Cumulative usage across entire conversation (aggregates all turns) Only set for conversation requests, not set for non-conversation requests

ResponseFormat Message

Response format configuration

Name Type Description
mode ResponseFormat.Mode
json_schema string JSON schema for JSON_SCHEMA mode

ResponseStarted Message

Name Type Description
conversation_name string
model_used string
available_tools repeated ToolInfo
capabilities ModelCapabilities

ResumeConfig Message

Resume configuration for editing conversation history

Name Type Description
from_turn int32 Resume conversation from this turn (0-indexed) The turn at from_turn and all turns after will be moved to replaced_turn_groups
replace_message Message Optional: Replacement message for this turn Can be role=“user” or role=“tool” depending on turn type If not set, uses the original message from that turn Must match the role of the first message in the original turn
resume_reason string Optional: User comment/reason for the resume operation Will be stored in ReplacedTurnGroup.resume_reason
resume_enabled bool Explicit enable flag to avoid ambiguity when clients send an empty struct If false or unset, server must treat this as not a resume request

RetrievalLimits Message

Name Type Description
max_documents uint32s
max_context_tokens uint32s
min_relevance_score float
require_citations bool

SearchDbChange Message

SearchDbChange is used by Watch notifications Responses to describe change of single SearchDb One of Added, Modified, Removed

Name Type Description
added SearchDbChange.Added Added is returned when watched document is added, either created or enters Query view
modified SearchDbChange.Modified Modified is returned when watched document is modified
current SearchDbChange.Current Current is returned in stateless watch when document enters query view or is modified within.
removed SearchDbChange.Removed Removed is returned when SearchDb is deleted or leaves Query view

SearchDbChange.Added Message

SearchDb has been added to query view

Name Type Description
search_db SearchDb
view_index int32 Integer describing index of added SearchDb in resulting query view.

SearchDbChange.Current Message

SearchDb has been added or modified in a query view. Version used for stateless watching

Name Type Description
search_db SearchDb

SearchDbChange.Modified Message

SearchDb changed some of it’s fields - contains either full document or masked change

Name Type Description
name string (name of SearchDb) Name of modified SearchDb
search_db SearchDb New version of SearchDb or masked difference, depending on mask_changes instrumentation of issued [WatchSearchDbRequest] or [WatchSearchDbsRequest]
field_mask .google.protobuf.FieldMask Used when mask_changes is set, contains field paths of modified properties.
previous_view_index int32 Previous view index specifies previous position of modified SearchDb. When modification doesn’t affect sorted order, value will remain identical to [view_index].
view_index int32 Integer specifying SearchDb new index in resulting query view.

SearchDbChange.Removed Message

Removed is returned when SearchDb is deleted or leaves Query view

Name Type Description
name string (name of SearchDb)
view_index int32 Integer specifying removed SearchDb index. Not populated in stateless watch type.

SearchIndexChange Message

SearchIndexChange is used by Watch notifications Responses to describe change of single SearchIndex One of Added, Modified, Removed

Name Type Description
added SearchIndexChange.Added Added is returned when watched document is added, either created or enters Query view
modified SearchIndexChange.Modified Modified is returned when watched document is modified
current SearchIndexChange.Current Current is returned in stateless watch when document enters query view or is modified within.
removed SearchIndexChange.Removed Removed is returned when SearchIndex is deleted or leaves Query view

SearchIndexChange.Added Message

SearchIndex has been added to query view

Name Type Description
search_index SearchIndex
view_index int32 Integer describing index of added SearchIndex in resulting query view.

SearchIndexChange.Current Message

SearchIndex has been added or modified in a query view. Version used for stateless watching

Name Type Description
search_index SearchIndex

SearchIndexChange.Modified Message

SearchIndex changed some of it’s fields - contains either full document or masked change

Name Type Description
name string (name of SearchIndex) Name of modified SearchIndex
search_index SearchIndex New version of SearchIndex or masked difference, depending on mask_changes instrumentation of issued [WatchSearchIndexRequest] or [WatchSearchIndicesRequest]
field_mask .google.protobuf.FieldMask Used when mask_changes is set, contains field paths of modified properties.
previous_view_index int32 Previous view index specifies previous position of modified SearchIndex. When modification doesn’t affect sorted order, value will remain identical to [view_index].
view_index int32 Integer specifying SearchIndex new index in resulting query view.

SearchIndexChange.Removed Message

Removed is returned when SearchIndex is deleted or leaves Query view

Name Type Description
name string (name of SearchIndex)
view_index int32 Integer specifying removed SearchIndex index. Not populated in stateless watch type.

SessionInitialized Message

Session initialization confirmation

Name Type Description
conversation_name string Conversation name (created or resumed)
model_used string Model that will be used for this session
capabilities ModelCapabilities Model capabilities

StartOauth Message

Initial event to kick off the OAuth handshake.

Name Type Description
return_to string SPA-relative path the backend should redirect back to after login.
scopes repeated string Optional additional scopes requested by the client.
login_hint string Optional login hint for the upstream Authorization Server.
prompt_params map<string, string> Provider-specific prompt parameters (prompt=consent, access_type=offline, etc).
parent string (parent name of ConnectorUserToken) Parent name of ntt.ai.v1.ConnectorUserToken. When provided, this determines the project scope under which the connector user token will be stored after a successful OAuth callback.

StreamError Message

Stream error information

Name Type Description
type StreamError.ErrorType
message string

TemplateVariable Message

Variable definition with UI guidance

Name Type Description
label string Form label (e.g., “Time range”)
help_text string Placeholder/help text
input_type InputType
suggestions repeated string Suggested values for SELECT or DURATION inputs
default_value string Optional client-side default value
resource_type string when input_type == RESOURCE

TextContent Message

Name Type Description
text string

ThinkingConfig Message

Thinking configuration for Anthropic models

Name Type Description
type ThinkingConfig.Type
budget_tokens int32 Budget for thinking tokens (must be ≥1024 and < max_tokens)

ThinkingContent Message

Thinking/reasoning content with optional signature

Name Type Description
text string
signature string

ThinkingDelta Message

Name Type Description
text string

ThinkingDone Message

Name Type Description
text string
signature string

TokenUsage Message

Token usage information

Name Type Description
input_tokens int32 === TOKEN TOTALS ===
output_tokens int32
total_tokens int32
input_breakdown InputTokenBreakdown === UNIVERSAL BREAKDOWNS (all providers map here) ===
output_breakdown OutputTokenBreakdown
metadata TokenUsageMetadata
input_cost .google.type.Money === COST BREAKDOWN (1:1 mapping to breakdown categories) === Costs are zero when pricing is unknown.
cached_input_cost .google.type.Money
cache_write_five_min_cost .google.type.Money
cache_write_one_hour_cost .google.type.Money
output_cost .google.type.Money
total_cost .google.type.Money

TokenUsageMetadata Message

Metadata about the request (provider, model, service tier)

Name Type Description
provider string
model string
service_tier string

ToolCall Message

Tool call for execution

Name Type Description
id string
name string
arguments string

ToolCalls Message

Tool calls container

Name Type Description
calls repeated ToolCall

ToolDefinition Message

Tool definition

Name Type Description
name string
description string
input_schema string
provider string

ToolExecution Message

Name Type Description
tool_call_id string
tool_name string
arguments string “github.createIssue”, “internal.rag.search”)
connector_name string (name of Connector)
capability_template_name string (name of CapabilityTemplate) For internal tools: just the template name Server will load the template and extract RAG config

ToolExecutionResult Message

Name Type Description
tool_call_id string TODO: replace with common ToolResponse once all clients accept the richer proto.
tool_name string
output string
error string
mime_type string
connector_auth_errors repeated ConnectorAuthError Connector authentication errors that blocked this tool execution. Empty for non-connector-related failures.

ToolInfo Message

Tool information including source

Name Type Description
name string
client ClientToolSource
connector ConnectorToolSource
internal InternalToolSource

ToolResponse Message

Tool response

Name Type Description
tool_call_id string
tool string
output Payload
error string

ToolSafetyConfig Message

Tool safety configuration for loop detection

Name Type Description
max_consecutive_tool_calls uint32s Maximum consecutive tool-calling assistant messages (default: 20) This detects infinite tool loops, NOT total tool usage. Counter resets when assistant message doesn’t contain tool calls. Example: 20 consecutive turns with tools → blocked 19 turns with tools + 1 text-only turn + 19 more → allowed
max_consecutive_identical_tool_calls uint32s Maximum consecutive identical tool+args calls (default: 3) This detects stuck loops where same tool+args is called repeatedly. Example: search_docs(“query”) called 3 times in a row → blocked search_docs(“query1”), search_docs(“query2”), … → allowed
max_consecutive_same_tool_calls uint32s Maximum consecutive calls to the same tool name (default: 6) Similar to the identical check but ignores arguments, only tool names. Example: search_docs(“q1”), search_docs(“q2”), … (same tool name) → blocked weather_lookup(…), search_docs(…), weather_lookup(…) → allowed

TurnConfig Message

Configuration snapshot for a single turn

Name Type Description
model string (name of ChatModel) Model selection
model_used string Actual model ID from ResponseStarted
temperature float Parameters
max_tokens int32
reasoning_level ReasoningLevel
capability_template string (name of CapabilityTemplate)
connectors ConnectorsList

TurnToolsBySourceGroup Message

Group tools by source to avoid duplicating source per tool

Name Type Description
client ClientToolSource
connector ConnectorToolSource
internal InternalToolSource
tool_names repeated string

URLReference Message

URL reference

Name Type Description
url string
filepath string

UserPromptTemplate Message

Prompt template for user-selectable prompt snippets These are client-side only - server stores metadata, client renders/executes

Name Type Description
display_name string Display name shown in template picker
description string Short explanation shown alongside the template picker entry
tags repeated string Tags for filtering/categorization (e.g., [“rca”, “historical”, “live-troubleshooting”])
template_text string The actual prompt text with {{placeholders}} Example: “Review this {{language}} code:\n\n{{code}}”
variables map<string, TemplateVariable> Template variables keyed by placeholder name

AI Service Shared Enumerations

Here is the list of AI service shared enumerations:

ConnectorAuthErrorCode Enumeration

ConnectorAuthErrorCode describes why connector OAuth auth failed for the current user in the context of a single API call.

Name Description
CONNECTOR_AUTH_ERROR_CODE_UNSPECIFIED
CONNECTOR_AUTH_ERROR_CODE_REQUIRED No connector OAuth token is available for this user.
CONNECTOR_AUTH_ERROR_CODE_EXPIRED Token exists but is expired and cannot be automatically refreshed.
CONNECTOR_AUTH_ERROR_CODE_REFRESH_FAILED Refresh attempt failed (e.g. provider returned invalid_grant/401).
CONNECTOR_AUTH_ERROR_CODE_DOWNSTREAM_CONSENT_REQUIRED Connector token exists and is still valid, but the provider requires an additional consent flow (e.g. downstream resource scopes) before it can be used successfully.

ContentChannel Enumeration

Content channel type

Name Description
CONTENT_CHANNEL_UNSPECIFIED
CONTENT_CHANNEL_CONTENT
CONTENT_CHANNEL_THINKING

InputType Enumeration

Supported input widgets for template variables

Name Description
INPUT_TYPE_UNSPECIFIED
TEXT
LONG_TEXT
SELECT
DATETIME
DATE_RANGE
DURATION
DURATION_OR_DATE_RANGE
NUMBER
RESOURCE
FILE
BOOL
URL
EMAIL

InternalToolSource.Type Enumeration

Name Description
TYPE_UNSPECIFIED
RAG

LLMError Enumeration

LLM/Provider specific errors

Name Description
LLM_ERROR_UNSPECIFIED
LLM_RATE_LIMIT
LLM_CONTENT_FILTER
LLM_PROVIDER_ERROR
LLM_TOOL_ERROR

Msg.Type Enumeration

Name Description
UNDEFINED
SYSTEM
ASSISTANT
USER
SEARCH_ITEMS

OauthCompletion.Status Enumeration

Name Description
STATUS_UNSPECIFIED
STATUS_SUCCESS
STATUS_CANCELLED
STATUS_TIMEOUT
STATUS_ERROR

PromptMissingVarPolicy Enumeration

Policy for how to handle missing variables during rendering

Name Description
PROMPT_MISSING_VAR_POLICY_ERROR
PROMPT_MISSING_VAR_POLICY_SKIP_APPEND

PromptVariableMode Enumeration

Variable source mode - determines where template variables come from Variables are auto-detected from template text (e.g., {{.userEmail}})

Name Description
MODE_SERVER Server-provided variables (trusted, from auth context) Rendered text is injected into the system prompt Known server variables: userEmail, projectName
MODE_CLIENT Client-provided variables (untrusted, sanitized) Rendered text is injected into the system prompt Variables looked up from CreateRequest.prompt_variables map

ProviderDone.StopReason Enumeration

Why the generation stopped

Name Description
STOP_REASON_UNSPECIFIED
STOP
LENGTH
TOOL_CALLS
CONTENT_FILTER
ERROR

ReasoningLevel Enumeration

Reasoning/thinking level for AI models

Name Description
REASONING_LEVEL_DEFAULT
REASONING_LEVEL_LOW
REASONING_LEVEL_MEDIUM
REASONING_LEVEL_HIGH

ResponseFormat.Mode Enumeration

Name Description
MODE_UNSPECIFIED
TEXT
JSON_OBJECT
JSON_SCHEMA

StopReason Enumeration

Stop reason for response generation

Name Description
STOP_REASON_UNSPECIFIED
STOP_REASON_COMPLETED
STOP_REASON_MAX_TOKENS
STOP_REASON_TOOL_CALLS
STOP_REASON_ERROR
STOP_REASON_CONTENT_FILTER

StreamError.ErrorType Enumeration

Name Description
ERROR_TYPE_UNSPECIFIED
RATE_LIMIT
CONTENT_FILTER
PROVIDER_ERROR

ThinkingConfig.Type Enumeration

Name Description
TYPE_UNSPECIFIED
ENABLED
DISABLED