How an account runs AI work: the connection that pays for it (its own Anthropic key, or the platform’s), the agent that says by which rules to run, the versioned instruction it renders, and the execution — one persistent run, with its model, its attempts, its tokens and its output. ai_models and ai_system_agents are the platform’s own read-only catalogues to build on.
List ai_agents
The reusable settings of an AI run in an account: which instruction it follows, which model it runs on, how hard it tries and how long it waits. Every change is a new version, and the settings of each version are kept, so what any run used can be looked up later.
path Parameters
account_idId of the parent account.
query Parameters
page_sizeRows per page. Over the maximum is clamped, not rejected.
page_tokenOpaque token from a previous next_page_token. A token minted under a different order_by/filter is rejected.
skipRows to skip before the page (AIP-158). skip + page_size is capped at 10000; beyond that is OUT_OF_RANGE.
order_byComma-separated field [asc|desc], at most 3 keys. Default: create_time desc. Sortable: create_time, display_name.
filterAIP-160 subset (§8). Filterable: allowed_model_ids, create_time, display_name, instruction_id, is_enabled, preferred_model_id, version. A field outside the list is INVALID_ARGUMENT.
List ai_agents › Responses
One page of ai_agents.
This page of ai_agents, in the requested order.
next_page_tokenOpaque. Absent or empty means this was the last page.
total_sizeRows in the whole filtered collection, not in this page.
Create ai_agent
Creates an agent at version 1. Name an instruction of the account with instruction_id, or set source_system_agent to copy a platform agent — its settings, and its instruction text as a new instruction of the account — with any other fields of the body applied over the copy.
Settings that could never run are refused here rather than at the first run: a model that is not AVAILABLE, an effort on a model without the EFFORT capability, a JSON agent on a model without STRUCTURED_OUTPUT, a max_tokens above the model's limit.
path Parameters
account_idId of the parent account.
Create ai_agent › Request Body
display_nameThe label that tells this agent apart in a list. Required on create unless source_system_agent supplies it.
descriptionWhat the agent is for, for the people who maintain it.
instruction_idThe id of the account's ai_instructions entry this agent runs. Required on create unless source_system_agent is set, which creates the instruction too.
instruction_versionPin the agent to one version of its instruction. Absent means the instruction's active_version at the moment a run starts.
preferred_model_idThe ai_models entry a run uses when it does not name a model. Must be AVAILABLE when set, and able to run what this agent asks of it.
allowed_model_idsThe only models a run of this agent may name. Empty means any available model; when not empty, it must include preferred_model_id.
max_tokensThe most tokens one run may write, at most the model's max_output_tokens. Defaults to 16000.
effortHow hard the model is asked to think: LOW, MEDIUM, HIGH, XHIGH or MAX. Leave it unset for the model's default — and on a model without the EFFORT capability, which refuses any level.
output_formatTEXT (the default); JSON — an answer that follows output_schema, on a model with STRUCTURED_OUTPUT; or IMAGE — a picture, on a model with IMAGE_GENERATION, whose rendered instruction is the prompt and whose result is an artifact of the run rather than text.
output_schemaThe JSON Schema object a JSON agent's answer must follow. Required when output_format is JSON and refused otherwise.
image_widthThe width of the picture an IMAGE agent asks for, in pixels, 64 to 4096; defaults to 1024. Refused on a TEXT or JSON agent.
image_heightThe height of the picture an IMAGE agent asks for, in pixels, 64 to 4096; defaults to 1024. Refused on a TEXT or JSON agent.
image_qualityHow much care an IMAGE agent's picture is drawn with: LOW, MEDIUM, HIGH, XHIGH or MAX. Interpreted by the model's provider: on openai it is the picture's quality, and a higher one produces more output tokens; bfl has no such setting and ignores it. Leave it unset for the provider's default. Refused on a TEXT or JSON agent.
connection_modeWhich of the account's connections a run may be authorized through: ANY (the default), BYOK_ONLY or MANAGED_ONLY.
max_attemptsHow many times a run is tried when the provider fails in a way worth retrying: 1 to 10, default 3.
timeoutHow long one call to the provider may take: a number of seconds with the s suffix, 1s to 600s. Defaults to 120s.
allowed_toolsTools the model may call. Must be empty: tool calling is not available yet.
is_enabledWhether the agent may run. Switch it off to stop new runs without deleting it.
source_system_agentCreate only: the id of an ai_system_agents entry to copy. Its settings and its instruction text — as a new instruction of this account — become the new agent's, under any fields the body also sets.
Create ai_agent › Responses
The created resource.
nameThe resource name (§5) — the identity of this resource, and the path that addresses it: websites/{website}/cms_pages/{cms_page}. It is the handle to store, not a human label.
idThe last segment of name on its own, for a client that needs to build a child URL. Unique inside its parent, never across the platform.
create_timeWhen the resource was created (RFC 3339, UTC).
update_timeWhen the resource last changed (RFC 3339, UTC).
etagVersion of the persisted state. Send it back in If-Match on Update or Delete and the write is rejected with ABORTED if anyone else changed the resource meanwhile (§14).
display_nameThe label that tells this agent apart in a list. Required on create unless source_system_agent supplies it.
descriptionWhat the agent is for, for the people who maintain it.
instruction_idThe id of the account's ai_instructions entry this agent runs. Required on create unless source_system_agent is set, which creates the instruction too.
instruction_versionPin the agent to one version of its instruction. Absent means the instruction's active_version at the moment a run starts.
preferred_model_idThe ai_models entry a run uses when it does not name a model. Must be AVAILABLE when set, and able to run what this agent asks of it.
allowed_model_idsThe only models a run of this agent may name. Empty means any available model; when not empty, it must include preferred_model_id.
max_tokensThe most tokens one run may write, at most the model's max_output_tokens. Defaults to 16000.
effortHow hard the model is asked to think: LOW, MEDIUM, HIGH, XHIGH or MAX. Leave it unset for the model's default — and on a model without the EFFORT capability, which refuses any level.
output_formatTEXT (the default); JSON — an answer that follows output_schema, on a model with STRUCTURED_OUTPUT; or IMAGE — a picture, on a model with IMAGE_GENERATION, whose rendered instruction is the prompt and whose result is an artifact of the run rather than text.
output_schemaThe JSON Schema object a JSON agent's answer must follow. Required when output_format is JSON and refused otherwise.
image_widthThe width of the picture an IMAGE agent asks for, in pixels, 64 to 4096; defaults to 1024. Refused on a TEXT or JSON agent.
image_heightThe height of the picture an IMAGE agent asks for, in pixels, 64 to 4096; defaults to 1024. Refused on a TEXT or JSON agent.
image_qualityHow much care an IMAGE agent's picture is drawn with: LOW, MEDIUM, HIGH, XHIGH or MAX. Interpreted by the model's provider: on openai it is the picture's quality, and a higher one produces more output tokens; bfl has no such setting and ignores it. Leave it unset for the provider's default. Refused on a TEXT or JSON agent.
connection_modeWhich of the account's connections a run may be authorized through: ANY (the default), BYOK_ONLY or MANAGED_ONLY.
max_attemptsHow many times a run is tried when the provider fails in a way worth retrying: 1 to 10, default 3.
timeoutHow long one call to the provider may take: a number of seconds with the s suffix, 1s to 600s. Defaults to 120s.
allowed_toolsTools the model may call. Must be empty: tool calling is not available yet.
is_enabledWhether the agent may run. Switch it off to stop new runs without deleting it.
versionThe configuration's version: 1 on create, and one more on every update. Each version's settings are kept under versions.
Get ai_agent
The reusable settings of an AI run in an account: which instruction it follows, which model it runs on, how hard it tries and how long it waits. Every change is a new version, and the settings of each version are kept, so what any run used can be looked up later.
path Parameters
account_idId of the parent account.
ai_agent_idId of the parent ai_agent.
Headers
If-None-MatchA matching etag answers 304 with no body (§16).
Get ai_agent › Responses
The resource.
nameThe resource name (§5) — the identity of this resource, and the path that addresses it: websites/{website}/cms_pages/{cms_page}. It is the handle to store, not a human label.
idThe last segment of name on its own, for a client that needs to build a child URL. Unique inside its parent, never across the platform.
create_timeWhen the resource was created (RFC 3339, UTC).
update_timeWhen the resource last changed (RFC 3339, UTC).
etagVersion of the persisted state. Send it back in If-Match on Update or Delete and the write is rejected with ABORTED if anyone else changed the resource meanwhile (§14).
display_nameThe label that tells this agent apart in a list. Required on create unless source_system_agent supplies it.
descriptionWhat the agent is for, for the people who maintain it.
instruction_idThe id of the account's ai_instructions entry this agent runs. Required on create unless source_system_agent is set, which creates the instruction too.
instruction_versionPin the agent to one version of its instruction. Absent means the instruction's active_version at the moment a run starts.
preferred_model_idThe ai_models entry a run uses when it does not name a model. Must be AVAILABLE when set, and able to run what this agent asks of it.
allowed_model_idsThe only models a run of this agent may name. Empty means any available model; when not empty, it must include preferred_model_id.
max_tokensThe most tokens one run may write, at most the model's max_output_tokens. Defaults to 16000.
effortHow hard the model is asked to think: LOW, MEDIUM, HIGH, XHIGH or MAX. Leave it unset for the model's default — and on a model without the EFFORT capability, which refuses any level.
output_formatTEXT (the default); JSON — an answer that follows output_schema, on a model with STRUCTURED_OUTPUT; or IMAGE — a picture, on a model with IMAGE_GENERATION, whose rendered instruction is the prompt and whose result is an artifact of the run rather than text.
output_schemaThe JSON Schema object a JSON agent's answer must follow. Required when output_format is JSON and refused otherwise.
image_widthThe width of the picture an IMAGE agent asks for, in pixels, 64 to 4096; defaults to 1024. Refused on a TEXT or JSON agent.
image_heightThe height of the picture an IMAGE agent asks for, in pixels, 64 to 4096; defaults to 1024. Refused on a TEXT or JSON agent.
image_qualityHow much care an IMAGE agent's picture is drawn with: LOW, MEDIUM, HIGH, XHIGH or MAX. Interpreted by the model's provider: on openai it is the picture's quality, and a higher one produces more output tokens; bfl has no such setting and ignores it. Leave it unset for the provider's default. Refused on a TEXT or JSON agent.
connection_modeWhich of the account's connections a run may be authorized through: ANY (the default), BYOK_ONLY or MANAGED_ONLY.
max_attemptsHow many times a run is tried when the provider fails in a way worth retrying: 1 to 10, default 3.
timeoutHow long one call to the provider may take: a number of seconds with the s suffix, 1s to 600s. Defaults to 120s.
allowed_toolsTools the model may call. Must be empty: tool calling is not available yet.
is_enabledWhether the agent may run. Switch it off to stop new runs without deleting it.
versionThe configuration's version: 1 on create, and one more on every update. Each version's settings are kept under versions.
Delete ai_agent
Deletes an agent. Its instruction is not deleted, and the settings of its versions are kept for the runs that used them, though they are no longer listed.
path Parameters
account_idId of the parent account.
ai_agent_idId of the parent ai_agent.
Headers
If-MatchThe etag the client last read. A mismatch is ABORTED (409) with the current resource in the error details (§14).
Delete ai_agent › Responses
Deleted. No body (§7).
Update ai_agent
Changes an agent's settings. Every update raises version by exactly one — even one that changes nothing — and keeps the settings of the version it replaces under versions. Send the etag in If-Match to be refused with ABORTED if someone else changed the agent first.
path Parameters
account_idId of the parent account.
ai_agent_idId of the parent ai_agent.
query Parameters
update_maskComma-separated field paths to merge. A field named here and sent as null is cleared; without the mask a null is dropped (§7, §11).
Headers
If-MatchThe etag the client last read. A mismatch is ABORTED (409) with the current resource in the error details (§14).
Update ai_agent › Request Body
display_nameThe label that tells this agent apart in a list. Required on create unless source_system_agent supplies it.
descriptionWhat the agent is for, for the people who maintain it.
instruction_idThe id of the account's ai_instructions entry this agent runs. Required on create unless source_system_agent is set, which creates the instruction too.
instruction_versionPin the agent to one version of its instruction. Absent means the instruction's active_version at the moment a run starts.
preferred_model_idThe ai_models entry a run uses when it does not name a model. Must be AVAILABLE when set, and able to run what this agent asks of it.
allowed_model_idsThe only models a run of this agent may name. Empty means any available model; when not empty, it must include preferred_model_id.
max_tokensThe most tokens one run may write, at most the model's max_output_tokens. Defaults to 16000.
effortHow hard the model is asked to think: LOW, MEDIUM, HIGH, XHIGH or MAX. Leave it unset for the model's default — and on a model without the EFFORT capability, which refuses any level.
output_formatTEXT (the default); JSON — an answer that follows output_schema, on a model with STRUCTURED_OUTPUT; or IMAGE — a picture, on a model with IMAGE_GENERATION, whose rendered instruction is the prompt and whose result is an artifact of the run rather than text.
output_schemaThe JSON Schema object a JSON agent's answer must follow. Required when output_format is JSON and refused otherwise.
image_widthThe width of the picture an IMAGE agent asks for, in pixels, 64 to 4096; defaults to 1024. Refused on a TEXT or JSON agent.
image_heightThe height of the picture an IMAGE agent asks for, in pixels, 64 to 4096; defaults to 1024. Refused on a TEXT or JSON agent.
image_qualityHow much care an IMAGE agent's picture is drawn with: LOW, MEDIUM, HIGH, XHIGH or MAX. Interpreted by the model's provider: on openai it is the picture's quality, and a higher one produces more output tokens; bfl has no such setting and ignores it. Leave it unset for the provider's default. Refused on a TEXT or JSON agent.
connection_modeWhich of the account's connections a run may be authorized through: ANY (the default), BYOK_ONLY or MANAGED_ONLY.
max_attemptsHow many times a run is tried when the provider fails in a way worth retrying: 1 to 10, default 3.
timeoutHow long one call to the provider may take: a number of seconds with the s suffix, 1s to 600s. Defaults to 120s.
allowed_toolsTools the model may call. Must be empty: tool calling is not available yet.
is_enabledWhether the agent may run. Switch it off to stop new runs without deleting it.
source_system_agentCreate only: the id of an ai_system_agents entry to copy. Its settings and its instruction text — as a new instruction of this account — become the new agent's, under any fields the body also sets.
Update ai_agent › Responses
The updated resource.
nameThe resource name (§5) — the identity of this resource, and the path that addresses it: websites/{website}/cms_pages/{cms_page}. It is the handle to store, not a human label.
idThe last segment of name on its own, for a client that needs to build a child URL. Unique inside its parent, never across the platform.
create_timeWhen the resource was created (RFC 3339, UTC).
update_timeWhen the resource last changed (RFC 3339, UTC).
etagVersion of the persisted state. Send it back in If-Match on Update or Delete and the write is rejected with ABORTED if anyone else changed the resource meanwhile (§14).
display_nameThe label that tells this agent apart in a list. Required on create unless source_system_agent supplies it.
descriptionWhat the agent is for, for the people who maintain it.
instruction_idThe id of the account's ai_instructions entry this agent runs. Required on create unless source_system_agent is set, which creates the instruction too.
instruction_versionPin the agent to one version of its instruction. Absent means the instruction's active_version at the moment a run starts.
preferred_model_idThe ai_models entry a run uses when it does not name a model. Must be AVAILABLE when set, and able to run what this agent asks of it.
allowed_model_idsThe only models a run of this agent may name. Empty means any available model; when not empty, it must include preferred_model_id.
max_tokensThe most tokens one run may write, at most the model's max_output_tokens. Defaults to 16000.
effortHow hard the model is asked to think: LOW, MEDIUM, HIGH, XHIGH or MAX. Leave it unset for the model's default — and on a model without the EFFORT capability, which refuses any level.
output_formatTEXT (the default); JSON — an answer that follows output_schema, on a model with STRUCTURED_OUTPUT; or IMAGE — a picture, on a model with IMAGE_GENERATION, whose rendered instruction is the prompt and whose result is an artifact of the run rather than text.
output_schemaThe JSON Schema object a JSON agent's answer must follow. Required when output_format is JSON and refused otherwise.
image_widthThe width of the picture an IMAGE agent asks for, in pixels, 64 to 4096; defaults to 1024. Refused on a TEXT or JSON agent.
image_heightThe height of the picture an IMAGE agent asks for, in pixels, 64 to 4096; defaults to 1024. Refused on a TEXT or JSON agent.
image_qualityHow much care an IMAGE agent's picture is drawn with: LOW, MEDIUM, HIGH, XHIGH or MAX. Interpreted by the model's provider: on openai it is the picture's quality, and a higher one produces more output tokens; bfl has no such setting and ignores it. Leave it unset for the provider's default. Refused on a TEXT or JSON agent.
connection_modeWhich of the account's connections a run may be authorized through: ANY (the default), BYOK_ONLY or MANAGED_ONLY.
max_attemptsHow many times a run is tried when the provider fails in a way worth retrying: 1 to 10, default 3.
timeoutHow long one call to the provider may take: a number of seconds with the s suffix, 1s to 600s. Defaults to 120s.
allowed_toolsTools the model may call. Must be empty: tool calling is not available yet.
is_enabledWhether the agent may run. Switch it off to stop new runs without deleting it.
versionThe configuration's version: 1 on create, and one more on every update. Each version's settings are kept under versions.
List versions
The immutable settings of an agent at one version, written by the update that produced it. create_time is when that version took effect, so the settings in force at any moment are those of the latest version created before it.
path Parameters
account_idId of the parent account.
ai_agent_idThe agent this is a version of. Fixed by the URL.
query Parameters
page_sizeRows per page. Over the maximum is clamped, not rejected.
page_tokenOpaque token from a previous next_page_token. A token minted under a different order_by/filter is rejected.
skipRows to skip before the page (AIP-158). skip + page_size is capped at 10000; beyond that is OUT_OF_RANGE.
order_byComma-separated field [asc|desc], at most 3 keys. Default: version desc. Sortable: version.
filterAIP-160 subset (§8). Filterable: created_by. A field outside the list is INVALID_ARGUMENT.
List versions › Responses
One page of versions.
This page of versions, in the requested order.
next_page_tokenOpaque. Absent or empty means this was the last page.
total_sizeRows in the whole filtered collection, not in this page.
Get version
The immutable settings of an agent at one version, written by the update that produced it. create_time is when that version took effect, so the settings in force at any moment are those of the latest version created before it.
path Parameters
account_idId of the parent account.
ai_agent_idThe agent this is a version of. Fixed by the URL.
versionThe version number — also this resource's id, and the version the agent had.
Headers
If-None-MatchA matching etag answers 304 with no body (§16).
Get version › Responses
The resource.
nameThe resource name (§5) — the identity of this resource, and the path that addresses it: websites/{website}/cms_pages/{cms_page}. It is the handle to store, not a human label.
idThe last segment of name on its own, for a client that needs to build a child URL. Unique inside its parent, never across the platform.
create_timeWhen the resource was created (RFC 3339, UTC).
update_timeWhen the resource last changed (RFC 3339, UTC).
etagVersion of the persisted state. Send it back in If-Match on Update or Delete and the write is rejected with ABORTED if anyone else changed the resource meanwhile (§14).
ai_agent_idThe agent this is a version of. Fixed by the URL.
versionThe version number — also this resource's id, and the version the agent had.
snapshotThe agent exactly as it stood at this version: every field of the agent resource, except etag.
created_byThe user whose write produced this version, as users/{user}.
List ai_connections
How an account's AI runs are authorized with a provider: its own API key (BYOK), or permission to use the platform's key and pay from the AI balance (MANAGED). Every account has one MANAGED connection per provider from the moment it exists; add BYOK connections for keys of your own.
path Parameters
account_idId of the parent account.
query Parameters
page_sizeRows per page. Over the maximum is clamped, not rejected.
page_tokenOpaque token from a previous next_page_token. A token minted under a different order_by/filter is rejected.
skipRows to skip before the page (AIP-158). skip + page_size is capped at 10000; beyond that is OUT_OF_RANGE.
order_byComma-separated field [asc|desc], at most 3 keys. Default: create_time desc. Sortable: create_time, display_name, last_verify_time.
filterAIP-160 subset (§8). Filterable: create_time, display_name, is_enabled, mode, provider, status. A field outside the list is INVALID_ARGUMENT.
List ai_connections › Responses
One page of ai_connections.
This page of ai_connections, in the requested order.
next_page_tokenOpaque. Absent or empty means this was the last page.
total_sizeRows in the whole filtered collection, not in this page.
Create ai_connection
Adds a way for the account's AI runs to be authorized. For your own provider key, send mode: BYOK with the api_key: it is encrypted before it is stored, only its last four characters come back as key_hint, and the connection starts UNVERIFIED — call :verify to have the provider confirm it.
The account's MANAGED connection for each provider already exists, so a MANAGED create answers ALREADY_EXISTS; api_key on a MANAGED connection is refused, because the platform's key is not the account's to set.
path Parameters
account_idId of the parent account.
Create ai_connection › Request Body
display_nameThe label that tells this connection apart in a list, such as Production key. Free text.
providerThe AI provider this connection reaches, by the platform's name for it. Set on create and fixed afterwards: a stored key belongs to exactly one provider.
modeBYOK — your own provider API key, used without touching your AI balance — or MANAGED, the platform's key, charged to the balance. Fixed after create.
api_keyThe provider API key. Required when creating a BYOK connection and refused on MANAGED; send it on Update to replace the stored key. It is encrypted before it is stored and no call ever returns it — key_hint is all that comes back.
is_enabledWhether runs may use this connection. Switch it off to stop a key being used without deleting it — and to turn managed access off for the account, since a MANAGED connection cannot be deleted.
priorityThe order connections are tried in when an agent may use more than one: lower goes first. Your keys start at 0 and the managed connection at 100, so a key you add is used before your balance is.
Create ai_connection › Responses
The created resource.
nameThe resource name (§5) — the identity of this resource, and the path that addresses it: websites/{website}/cms_pages/{cms_page}. It is the handle to store, not a human label.
idThe last segment of name on its own, for a client that needs to build a child URL. Unique inside its parent, never across the platform.
create_timeWhen the resource was created (RFC 3339, UTC).
update_timeWhen the resource last changed (RFC 3339, UTC).
etagVersion of the persisted state. Send it back in If-Match on Update or Delete and the write is rejected with ABORTED if anyone else changed the resource meanwhile (§14).
providerThe AI provider this connection reaches, by the platform's name for it. Set on create and fixed afterwards: a stored key belongs to exactly one provider.
modeBYOK — your own provider API key, used without touching your AI balance — or MANAGED, the platform's key, charged to the balance. Fixed after create.
display_nameThe label that tells this connection apart in a list, such as Production key. Free text.
key_hintThe last four characters of the stored key — the only part of it any response carries, so that two keys can be told apart. Absent on a MANAGED connection, which has no key of its own.
is_enabledWhether runs may use this connection. Switch it off to stop a key being used without deleting it — and to turn managed access off for the account, since a MANAGED connection cannot be deleted.
priorityThe order connections are tried in when an agent may use more than one: lower goes first. Your keys start at 0 and the managed connection at 100, so a key you add is used before your balance is.
statusWhat the platform last learned about the key: UNVERIFIED until it is checked, then VALID or INVALID — moved by :verify, and by a run the provider refused for the key's sake. EXPIRED is reserved for providers that report it. Always UNVERIFIED on a MANAGED connection, which has no key of its own to learn anything about.
last_verify_timeWhen status was last decided by asking the provider (RFC 3339, UTC); cleared when the key is replaced, and absent on a MANAGED connection. Sort by it together with a provider filter — that is the pair an index backs.
Get ai_connection
How an account's AI runs are authorized with a provider: its own API key (BYOK), or permission to use the platform's key and pay from the AI balance (MANAGED). Every account has one MANAGED connection per provider from the moment it exists; add BYOK connections for keys of your own.
path Parameters
account_idId of the parent account.
ai_connection_idId of the parent ai_connection.
Headers
If-None-MatchA matching etag answers 304 with no body (§16).
Get ai_connection › Responses
The resource.
nameThe resource name (§5) — the identity of this resource, and the path that addresses it: websites/{website}/cms_pages/{cms_page}. It is the handle to store, not a human label.
idThe last segment of name on its own, for a client that needs to build a child URL. Unique inside its parent, never across the platform.
create_timeWhen the resource was created (RFC 3339, UTC).
update_timeWhen the resource last changed (RFC 3339, UTC).
etagVersion of the persisted state. Send it back in If-Match on Update or Delete and the write is rejected with ABORTED if anyone else changed the resource meanwhile (§14).
providerThe AI provider this connection reaches, by the platform's name for it. Set on create and fixed afterwards: a stored key belongs to exactly one provider.
modeBYOK — your own provider API key, used without touching your AI balance — or MANAGED, the platform's key, charged to the balance. Fixed after create.
display_nameThe label that tells this connection apart in a list, such as Production key. Free text.
key_hintThe last four characters of the stored key — the only part of it any response carries, so that two keys can be told apart. Absent on a MANAGED connection, which has no key of its own.
is_enabledWhether runs may use this connection. Switch it off to stop a key being used without deleting it — and to turn managed access off for the account, since a MANAGED connection cannot be deleted.
priorityThe order connections are tried in when an agent may use more than one: lower goes first. Your keys start at 0 and the managed connection at 100, so a key you add is used before your balance is.
statusWhat the platform last learned about the key: UNVERIFIED until it is checked, then VALID or INVALID — moved by :verify, and by a run the provider refused for the key's sake. EXPIRED is reserved for providers that report it. Always UNVERIFIED on a MANAGED connection, which has no key of its own to learn anything about.
last_verify_timeWhen status was last decided by asking the provider (RFC 3339, UTC); cleared when the key is replaced, and absent on a MANAGED connection. Sort by it together with a provider filter — that is the pair an index backs.
Delete ai_connection
Removes a BYOK connection and the key stored with it, for good. Runs stop using it at once. The account's MANAGED connection cannot be deleted — switch it off with is_enabled: false, which is how an account turns managed access off.
path Parameters
account_idId of the parent account.
ai_connection_idId of the parent ai_connection.
Headers
If-MatchThe etag the client last read. A mismatch is ABORTED (409) with the current resource in the error details (§14).
Delete ai_connection › Responses
Deleted. No body (§7).
Update ai_connection
Renames a connection, switches it on or off, or changes the order it is tried in. Sending a new api_key replaces the stored key: the old one is gone, key_hint changes, and the connection is UNVERIFIED again until it is checked — a verdict about the previous key says nothing about this one. provider and mode cannot be changed; create another connection.
path Parameters
account_idId of the parent account.
ai_connection_idId of the parent ai_connection.
query Parameters
update_maskComma-separated field paths to merge. A field named here and sent as null is cleared; without the mask a null is dropped (§7, §11).
Headers
If-MatchThe etag the client last read. A mismatch is ABORTED (409) with the current resource in the error details (§14).
Update ai_connection › Request Body
display_nameThe label that tells this connection apart in a list, such as Production key. Free text.
api_keyThe provider API key. Required when creating a BYOK connection and refused on MANAGED; send it on Update to replace the stored key. It is encrypted before it is stored and no call ever returns it — key_hint is all that comes back.
is_enabledWhether runs may use this connection. Switch it off to stop a key being used without deleting it — and to turn managed access off for the account, since a MANAGED connection cannot be deleted.
priorityThe order connections are tried in when an agent may use more than one: lower goes first. Your keys start at 0 and the managed connection at 100, so a key you add is used before your balance is.
Update ai_connection › Responses
The updated resource.
nameThe resource name (§5) — the identity of this resource, and the path that addresses it: websites/{website}/cms_pages/{cms_page}. It is the handle to store, not a human label.
idThe last segment of name on its own, for a client that needs to build a child URL. Unique inside its parent, never across the platform.
create_timeWhen the resource was created (RFC 3339, UTC).
update_timeWhen the resource last changed (RFC 3339, UTC).
etagVersion of the persisted state. Send it back in If-Match on Update or Delete and the write is rejected with ABORTED if anyone else changed the resource meanwhile (§14).
providerThe AI provider this connection reaches, by the platform's name for it. Set on create and fixed afterwards: a stored key belongs to exactly one provider.
modeBYOK — your own provider API key, used without touching your AI balance — or MANAGED, the platform's key, charged to the balance. Fixed after create.
display_nameThe label that tells this connection apart in a list, such as Production key. Free text.
key_hintThe last four characters of the stored key — the only part of it any response carries, so that two keys can be told apart. Absent on a MANAGED connection, which has no key of its own.
is_enabledWhether runs may use this connection. Switch it off to stop a key being used without deleting it — and to turn managed access off for the account, since a MANAGED connection cannot be deleted.
priorityThe order connections are tried in when an agent may use more than one: lower goes first. Your keys start at 0 and the managed connection at 100, so a key you add is used before your balance is.
statusWhat the platform last learned about the key: UNVERIFIED until it is checked, then VALID or INVALID — moved by :verify, and by a run the provider refused for the key's sake. EXPIRED is reserved for providers that report it. Always UNVERIFIED on a MANAGED connection, which has no key of its own to learn anything about.
last_verify_timeWhen status was last decided by asking the provider (RFC 3339, UTC); cleared when the key is replaced, and absent on a MANAGED connection. Sort by it together with a provider filter — that is the pair an index backs.
Verify (ai_connections)
Asks the provider whether this connection's key still works, and records the answer: status becomes VALID or INVALID and last_verify_time is set. It uses the cheapest request that can tell, and costs no tokens. Answers with the connection either way — an INVALID key is the answer this call exists to give, not an error.
For a BYOK connection only. A MANAGED connection has no key of its own, so this call answers FAILED_PRECONDITION on one: the platform's key is checked by the platform.
When the provider cannot be reached the call fails with UNAVAILABLE and nothing is changed: not being able to ask says nothing about the key. Safe to repeat.
path Parameters
account_idId of the parent account.
ai_connection_idId of the parent ai_connection.
Verify (ai_connections) › Request Body optional
Verify (ai_connections) › Responses
The affected resource, or the method’s own response object (§10).
List ai_executions
One run of an agent in an account: what was asked, which model and connection ran it, what came back, what it consumed, and every attempt in between. Runs are carried out in the background — create one, then read it until state is final.
path Parameters
account_idId of the parent account.
query Parameters
page_sizeRows per page. Over the maximum is clamped, not rejected.
page_tokenOpaque token from a previous next_page_token. A token minted under a different order_by/filter is rejected.
skipRows to skip before the page (AIP-158). skip + page_size is capped at 10000; beyond that is OUT_OF_RANGE.
order_byComma-separated field [asc|desc], at most 3 keys. Default: create_time desc. Sortable: create_time, expire_time.
filterAIP-160 subset (§8). Filterable: agent_id, connection_id, connection_mode, create_time, end_time, expire_time, model_id, provider, source_id, source_module, start_time, state. A field outside the list is INVALID_ARGUMENT.
List ai_executions › Responses
One page of ai_executions.
This page of ai_executions, in the requested order.
next_page_tokenOpaque. Absent or empty means this was the last page.
total_sizeRows in the whole filtered collection, not in this page.
Create ai_execution
Starts a run of an agent and answers at once with the run, QUEUED: the work happens in the background, so read the run until state is SUCCEEDED, FAILED, CANCELLED or EXPIRED. The run uses the agent's current version and its instruction's active (or pinned) version, and keeps using them even if either changes before it starts.
Refused before anything is queued: an input that does not fill exactly the variables the instruction uses, a model_id the agent cannot run on, an agent that is switched off, and an account with no connection the agent may use (FAILED_PRECONDITION, NO_USABLE_CONNECTION). Send a request_id to make the call safe to repeat: a repeat returns the first run.
path Parameters
account_idId of the parent account.
Create ai_execution › Request Body
agent_idThe id of the account's ai_agents entry this run executes. Set on create and fixed afterwards.
inputWhat the run works on: variables, an object filling every {{variable}} the instruction uses (strings, integers or booleans), and optionally text — material for the instruction to act on, such as a page to translate.
model_idThe ai_models entry the run uses. Leave it out to use the agent's preferred_model_id; when the agent lists allowed_model_ids, only those can be named.
source_moduleWho started the run, in the caller's own words — editorial, import. Stored and filterable, never interpreted. Fixed after create.
source_idThe caller's own reference for what the run is for, within source_module, which it requires. Filter by it together with source_module.
metadataAny other correlation the caller wants back with the run, as an object of at most 16 KB. Returned as sent; not filterable.
expire_timeA deadline for starting: a run not started by then becomes EXPIRED without calling the provider (RFC 3339, UTC). Sort by it together with a state filter.
request_idAn idempotency key you choose, at most 64 characters. Creating with a key already used returns the run that key created instead of starting another.
Create ai_execution › Responses
The created resource.
nameThe resource name (§5) — the identity of this resource, and the path that addresses it: websites/{website}/cms_pages/{cms_page}. It is the handle to store, not a human label.
idThe last segment of name on its own, for a client that needs to build a child URL. Unique inside its parent, never across the platform.
create_timeWhen the resource was created (RFC 3339, UTC).
update_timeWhen the resource last changed (RFC 3339, UTC).
etagVersion of the persisted state. Send it back in If-Match on Update or Delete and the write is rejected with ABORTED if anyone else changed the resource meanwhile (§14).
agent_idThe id of the account's ai_agents entry this run executes. Set on create and fixed afterwards.
agent_versionThe version of the agent this run uses, resolved when the run was created. Its settings are kept under the agent's versions, so the run can be reproduced after the agent changes.
instruction_versionThe version of the agent's instruction whose text this run uses, resolved when the run was created.
model_idThe ai_models entry the run uses. Leave it out to use the agent's preferred_model_id; when the agent lists allowed_model_ids, only those can be named.
providerThe AI provider of the run's model, by the platform's name for it.
inputWhat the run works on: variables, an object filling every {{variable}} the instruction uses (strings, integers or booleans), and optionally text — material for the instruction to act on, such as a page to translate.
stateQUEUED, RUNNING, then SUCCEEDED, FAILED, CANCELLED or EXPIRED. A retryable failure puts the run back to QUEUED until its attempts run out.
connection_idThe ai_connections entry the latest attempt was authorized through. Absent until an attempt was routed.
connection_modeWhose key the latest attempt used: BYOK (the account's own) or MANAGED (the platform's, paid from the AI balance).
usageWhat the run consumed, summed over every attempt that reported it: input_tokens, output_tokens, cache_read_input_tokens, cache_creation_input_tokens, and for an IMAGE run image_count and megapixels_milli (thousandths of a megapixel).
costWhat the run was charged to the AI balance, summed over its attempts, as Money. Present once an attempt on the platform's key (MANAGED) was charged; a run on the account's own key has no cost here, because the provider bills the account directly.
outputThe result of a SUCCEEDED run: text, or json for an agent with output_format JSON, or artifacts for an IMAGE agent — each with its storage_key, mime_type, width, height and byte_size, the bytes living in the platform's store — and output_truncated, true when a text answer stopped at max_tokens.
errorWhy a FAILED or EXPIRED run stopped, in the same shape as an API error: code, status, message and, where there is one, a PRECONDITION_FAILURE whose type says why.
attemptsEvery attempt, in order: number, start_time, end_time, http_status (0 when no response arrived), error_code, message, and usage when the attempt's usage is known.
source_moduleWho started the run, in the caller's own words — editorial, import. Stored and filterable, never interpreted. Fixed after create.
source_idThe caller's own reference for what the run is for, within source_module, which it requires. Filter by it together with source_module.
metadataAny other correlation the caller wants back with the run, as an object of at most 16 KB. Returned as sent; not filterable.
expire_timeA deadline for starting: a run not started by then becomes EXPIRED without calling the provider (RFC 3339, UTC). Sort by it together with a state filter.
start_timeWhen the first attempt started (RFC 3339, UTC).
end_timeWhen the run reached the state it is in, if that state is final (RFC 3339, UTC).
Get ai_execution
One run of an agent in an account: what was asked, which model and connection ran it, what came back, what it consumed, and every attempt in between. Runs are carried out in the background — create one, then read it until state is final.
path Parameters
account_idId of the parent account.
ai_execution_idId of the parent ai_execution.
Headers
If-None-MatchA matching etag answers 304 with no body (§16).
Get ai_execution › Responses
The resource.
nameThe resource name (§5) — the identity of this resource, and the path that addresses it: websites/{website}/cms_pages/{cms_page}. It is the handle to store, not a human label.
idThe last segment of name on its own, for a client that needs to build a child URL. Unique inside its parent, never across the platform.
create_timeWhen the resource was created (RFC 3339, UTC).
update_timeWhen the resource last changed (RFC 3339, UTC).
etagVersion of the persisted state. Send it back in If-Match on Update or Delete and the write is rejected with ABORTED if anyone else changed the resource meanwhile (§14).
agent_idThe id of the account's ai_agents entry this run executes. Set on create and fixed afterwards.
agent_versionThe version of the agent this run uses, resolved when the run was created. Its settings are kept under the agent's versions, so the run can be reproduced after the agent changes.
instruction_versionThe version of the agent's instruction whose text this run uses, resolved when the run was created.
model_idThe ai_models entry the run uses. Leave it out to use the agent's preferred_model_id; when the agent lists allowed_model_ids, only those can be named.
providerThe AI provider of the run's model, by the platform's name for it.
inputWhat the run works on: variables, an object filling every {{variable}} the instruction uses (strings, integers or booleans), and optionally text — material for the instruction to act on, such as a page to translate.
stateQUEUED, RUNNING, then SUCCEEDED, FAILED, CANCELLED or EXPIRED. A retryable failure puts the run back to QUEUED until its attempts run out.
connection_idThe ai_connections entry the latest attempt was authorized through. Absent until an attempt was routed.
connection_modeWhose key the latest attempt used: BYOK (the account's own) or MANAGED (the platform's, paid from the AI balance).
usageWhat the run consumed, summed over every attempt that reported it: input_tokens, output_tokens, cache_read_input_tokens, cache_creation_input_tokens, and for an IMAGE run image_count and megapixels_milli (thousandths of a megapixel).
costWhat the run was charged to the AI balance, summed over its attempts, as Money. Present once an attempt on the platform's key (MANAGED) was charged; a run on the account's own key has no cost here, because the provider bills the account directly.
outputThe result of a SUCCEEDED run: text, or json for an agent with output_format JSON, or artifacts for an IMAGE agent — each with its storage_key, mime_type, width, height and byte_size, the bytes living in the platform's store — and output_truncated, true when a text answer stopped at max_tokens.
errorWhy a FAILED or EXPIRED run stopped, in the same shape as an API error: code, status, message and, where there is one, a PRECONDITION_FAILURE whose type says why.
attemptsEvery attempt, in order: number, start_time, end_time, http_status (0 when no response arrived), error_code, message, and usage when the attempt's usage is known.
source_moduleWho started the run, in the caller's own words — editorial, import. Stored and filterable, never interpreted. Fixed after create.
source_idThe caller's own reference for what the run is for, within source_module, which it requires. Filter by it together with source_module.
metadataAny other correlation the caller wants back with the run, as an object of at most 16 KB. Returned as sent; not filterable.
expire_timeA deadline for starting: a run not started by then becomes EXPIRED without calling the provider (RFC 3339, UTC). Sort by it together with a state filter.
start_timeWhen the first attempt started (RFC 3339, UTC).
end_timeWhen the run reached the state it is in, if that state is final (RFC 3339, UTC).
Cancel (ai_executions)
Stops a run. A QUEUED run is CANCELLED at once. A RUNNING run cannot be interrupted mid-call — the provider finishes what it was sent — so the cancel is recorded and the run becomes CANCELLED as soon as that call returns, without its output; until then it still reads RUNNING. A run that has already finished answers FAILED_PRECONDITION (EXECUTION_FINISHED). Safe to repeat.
path Parameters
account_idId of the parent account.
ai_execution_idId of the parent ai_execution.
Cancel (ai_executions) › Request Body optional
Cancel (ai_executions) › Responses
The affected resource, or the method’s own response object (§10).
Retry (ai_executions)
Runs a FAILED run again: it goes back to QUEUED with a fresh set of the agent's max_attempts, and the new attempts are added to attempts after the old ones, numbered on. It runs with the same agent version, instruction version, model and input. Any other state answers FAILED_PRECONDITION (EXECUTION_NOT_FAILED), as does a run past its expire_time.
path Parameters
account_idId of the parent account.
ai_execution_idId of the parent ai_execution.
Retry (ai_executions) › Request Body optional
Retry (ai_executions) › Responses
The affected resource, or the method’s own response object (§10).
List ai_instructions
A prompt template of an account, kept apart from the agents that use it so that its text has a history. The text itself lives in versions: writing a version is the only way to change it, and active_version says which one runs.
path Parameters
account_idId of the parent account.
query Parameters
page_sizeRows per page. Over the maximum is clamped, not rejected.
page_tokenOpaque token from a previous next_page_token. A token minted under a different order_by/filter is rejected.
skipRows to skip before the page (AIP-158). skip + page_size is capped at 10000; beyond that is OUT_OF_RANGE.
order_byComma-separated field [asc|desc], at most 3 keys. Default: create_time desc. Sortable: create_time, display_name.
filterAIP-160 subset (§8). Filterable: create_time, display_name. A field outside the list is INVALID_ARGUMENT.
List ai_instructions › Responses
One page of ai_instructions.
This page of ai_instructions, in the requested order.
next_page_tokenOpaque. Absent or empty means this was the last page.
total_sizeRows in the whole filtered collection, not in this page.
Create ai_instruction
Creates an instruction with its name and the variables its text may use, and no text yet: write the text as its first version (POST …/versions), which becomes the active one.
path Parameters
account_idId of the parent account.
Create ai_instruction › Request Body
display_nameThe label that tells this instruction apart in a list. Free text.
descriptionWhat the instruction is for, for the people who maintain it.
variablesThe variable names the text may reference as {{name}}: lower-case letters, digits and _. A version that references a name not listed here is refused, and so is a run that supplies one — or leaves a referenced one out.
active_versionThe version a run uses unless its agent pins another. The first version becomes active by itself; after that, set this field to switch. Absent until a version exists.
Create ai_instruction › Responses
The created resource.
nameThe resource name (§5) — the identity of this resource, and the path that addresses it: websites/{website}/cms_pages/{cms_page}. It is the handle to store, not a human label.
idThe last segment of name on its own, for a client that needs to build a child URL. Unique inside its parent, never across the platform.
create_timeWhen the resource was created (RFC 3339, UTC).
update_timeWhen the resource last changed (RFC 3339, UTC).
etagVersion of the persisted state. Send it back in If-Match on Update or Delete and the write is rejected with ABORTED if anyone else changed the resource meanwhile (§14).
display_nameThe label that tells this instruction apart in a list. Free text.
descriptionWhat the instruction is for, for the people who maintain it.
variablesThe variable names the text may reference as {{name}}: lower-case letters, digits and _. A version that references a name not listed here is refused, and so is a run that supplies one — or leaves a referenced one out.
active_versionThe version a run uses unless its agent pins another. The first version becomes active by itself; after that, set this field to switch. Absent until a version exists.
Get ai_instruction
A prompt template of an account, kept apart from the agents that use it so that its text has a history. The text itself lives in versions: writing a version is the only way to change it, and active_version says which one runs.
path Parameters
account_idId of the parent account.
ai_instruction_idId of the parent ai_instruction.
Headers
If-None-MatchA matching etag answers 304 with no body (§16).
Get ai_instruction › Responses
The resource.
nameThe resource name (§5) — the identity of this resource, and the path that addresses it: websites/{website}/cms_pages/{cms_page}. It is the handle to store, not a human label.
idThe last segment of name on its own, for a client that needs to build a child URL. Unique inside its parent, never across the platform.
create_timeWhen the resource was created (RFC 3339, UTC).
update_timeWhen the resource last changed (RFC 3339, UTC).
etagVersion of the persisted state. Send it back in If-Match on Update or Delete and the write is rejected with ABORTED if anyone else changed the resource meanwhile (§14).
display_nameThe label that tells this instruction apart in a list. Free text.
descriptionWhat the instruction is for, for the people who maintain it.
variablesThe variable names the text may reference as {{name}}: lower-case letters, digits and _. A version that references a name not listed here is refused, and so is a run that supplies one — or leaves a referenced one out.
active_versionThe version a run uses unless its agent pins another. The first version becomes active by itself; after that, set this field to switch. Absent until a version exists.
Delete ai_instruction
Deletes an instruction that no agent uses; while one does, the call fails with FAILED_PRECONDITION (INSTRUCTION_IN_USE). Past runs keep the text they used.
path Parameters
account_idId of the parent account.
ai_instruction_idId of the parent ai_instruction.
Headers
If-MatchThe etag the client last read. A mismatch is ABORTED (409) with the current resource in the error details (§14).
Delete ai_instruction › Responses
Deleted. No body (§7).
Update ai_instruction
Renames an instruction, changes its variables, or switches the version that runs by setting active_version. The text itself does not change here — create a version for that. A change that would leave the active version referencing an undeclared variable is refused.
path Parameters
account_idId of the parent account.
ai_instruction_idId of the parent ai_instruction.
query Parameters
update_maskComma-separated field paths to merge. A field named here and sent as null is cleared; without the mask a null is dropped (§7, §11).
Headers
If-MatchThe etag the client last read. A mismatch is ABORTED (409) with the current resource in the error details (§14).
Update ai_instruction › Request Body
display_nameThe label that tells this instruction apart in a list. Free text.
descriptionWhat the instruction is for, for the people who maintain it.
variablesThe variable names the text may reference as {{name}}: lower-case letters, digits and _. A version that references a name not listed here is refused, and so is a run that supplies one — or leaves a referenced one out.
active_versionThe version a run uses unless its agent pins another. The first version becomes active by itself; after that, set this field to switch. Absent until a version exists.
Update ai_instruction › Responses
The updated resource.
nameThe resource name (§5) — the identity of this resource, and the path that addresses it: websites/{website}/cms_pages/{cms_page}. It is the handle to store, not a human label.
idThe last segment of name on its own, for a client that needs to build a child URL. Unique inside its parent, never across the platform.
create_timeWhen the resource was created (RFC 3339, UTC).
update_timeWhen the resource last changed (RFC 3339, UTC).
etagVersion of the persisted state. Send it back in If-Match on Update or Delete and the write is rejected with ABORTED if anyone else changed the resource meanwhile (§14).
display_nameThe label that tells this instruction apart in a list. Free text.
descriptionWhat the instruction is for, for the people who maintain it.
variablesThe variable names the text may reference as {{name}}: lower-case letters, digits and _. A version that references a name not listed here is refused, and so is a run that supplies one — or leaves a referenced one out.
active_versionThe version a run uses unless its agent pins another. The first version becomes active by itself; after that, set this field to switch. Absent until a version exists.
List versions
An immutable text of an instruction. Versions are numbered from 1 and never edited or deleted: to change the text, create the next version, then point the instruction's active_version at it if it is not the first.
path Parameters
account_idId of the parent account.
ai_instruction_idThe instruction this is a version of. Fixed by the URL.
query Parameters
page_sizeRows per page. Over the maximum is clamped, not rejected.
page_tokenOpaque token from a previous next_page_token. A token minted under a different order_by/filter is rejected.
skipRows to skip before the page (AIP-158). skip + page_size is capped at 10000; beyond that is OUT_OF_RANGE.
order_byComma-separated field [asc|desc], at most 3 keys. Default: version desc. Sortable: version.
filterAIP-160 subset (§8). Filterable: created_by. A field outside the list is INVALID_ARGUMENT.
List versions › Responses
One page of versions.
This page of versions, in the requested order.
next_page_tokenOpaque. Absent or empty means this was the last page.
total_sizeRows in the whole filtered collection, not in this page.
Create version
Writes the next text of an instruction — the only way its text changes. The number is assigned by the server. The text may reference only the instruction's variables. The first version of an instruction becomes its active_version; a later one runs once the instruction is updated to point at it.
path Parameters
account_idId of the parent account.
ai_instruction_idThe instruction this is a version of. Fixed by the URL.
Create version › Request Body
contentThe template text. {{name}} is replaced by the run's value for name, which must be one of the instruction's variables; any other text, other braces included, is sent as written.
notesWhy this version exists — the one thing a comparison of two texts cannot tell you.
Create version › Responses
The created resource.
nameThe resource name (§5) — the identity of this resource, and the path that addresses it: websites/{website}/cms_pages/{cms_page}. It is the handle to store, not a human label.
idThe last segment of name on its own, for a client that needs to build a child URL. Unique inside its parent, never across the platform.
create_timeWhen the resource was created (RFC 3339, UTC).
update_timeWhen the resource last changed (RFC 3339, UTC).
etagVersion of the persisted state. Send it back in If-Match on Update or Delete and the write is rejected with ABORTED if anyone else changed the resource meanwhile (§14).
ai_instruction_idThe instruction this is a version of. Fixed by the URL.
versionThe version number — also this resource's id. Assigned by the server: one more than the instruction's latest.
contentThe template text. {{name}} is replaced by the run's value for name, which must be one of the instruction's variables; any other text, other braces included, is sent as written.
notesWhy this version exists — the one thing a comparison of two texts cannot tell you.
created_byThe user who wrote this version, as users/{user}.
Get version
An immutable text of an instruction. Versions are numbered from 1 and never edited or deleted: to change the text, create the next version, then point the instruction's active_version at it if it is not the first.
path Parameters
account_idId of the parent account.
ai_instruction_idThe instruction this is a version of. Fixed by the URL.
versionThe version number — also this resource's id. Assigned by the server: one more than the instruction's latest.
Headers
If-None-MatchA matching etag answers 304 with no body (§16).
Get version › Responses
The resource.
nameThe resource name (§5) — the identity of this resource, and the path that addresses it: websites/{website}/cms_pages/{cms_page}. It is the handle to store, not a human label.
idThe last segment of name on its own, for a client that needs to build a child URL. Unique inside its parent, never across the platform.
create_timeWhen the resource was created (RFC 3339, UTC).
update_timeWhen the resource last changed (RFC 3339, UTC).
etagVersion of the persisted state. Send it back in If-Match on Update or Delete and the write is rejected with ABORTED if anyone else changed the resource meanwhile (§14).
ai_instruction_idThe instruction this is a version of. Fixed by the URL.
versionThe version number — also this resource's id. Assigned by the server: one more than the instruction's latest.
contentThe template text. {{name}} is replaced by the run's value for name, which must be one of the instruction's variables; any other text, other braces included, is sent as written.
notesWhy this version exists — the one thing a comparison of two texts cannot tell you.
created_byThe user who wrote this version, as users/{user}.
List ai_models
The models an AI agent can run on, with what each one can do. The catalogue belongs to the platform: read it to choose an agent's preferred_model_id. Prices are not part of a model — platform_priced says only whether there is one; what a run costs is recorded on the run.
query Parameters
page_sizeRows per page. Over the maximum is clamped, not rejected.
page_tokenOpaque token from a previous next_page_token. A token minted under a different order_by/filter is rejected.
skipRows to skip before the page (AIP-158). skip + page_size is capped at 10000; beyond that is OUT_OF_RANGE.
order_byComma-separated field [asc|desc], at most 3 keys. Default: display_name asc. Sortable: create_time, display_name.
filterAIP-160 subset (§8). Filterable: capabilities, create_time, display_name, external_id, provider, state, tier. A field outside the list is INVALID_ARGUMENT.
List ai_models › Responses
One page of ai_models.
This page of ai_models, in the requested order.
next_page_tokenOpaque. Absent or empty means this was the last page.
total_sizeRows in the whole filtered collection, not in this page.
Get ai_model
The models an AI agent can run on, with what each one can do. The catalogue belongs to the platform: read it to choose an agent's preferred_model_id. Prices are not part of a model — platform_priced says only whether there is one; what a run costs is recorded on the run.
path Parameters
ai_model_idId of the parent ai_model.
Headers
If-None-MatchA matching etag answers 304 with no body (§16).
Get ai_model › Responses
The resource.
nameThe resource name (§5) — the identity of this resource, and the path that addresses it: websites/{website}/cms_pages/{cms_page}. It is the handle to store, not a human label.
idThe last segment of name on its own, for a client that needs to build a child URL. Unique inside its parent, never across the platform.
create_timeWhen the resource was created (RFC 3339, UTC).
update_timeWhen the resource last changed (RFC 3339, UTC).
etagVersion of the persisted state. Send it back in If-Match on Update or Delete and the write is rejected with ABORTED if anyone else changed the resource meanwhile (§14).
providerThe provider that serves this model, by the platform's name for it.
external_idThe provider's own identifier for the model — what a run sends it. It can move to a newer snapshot of the model while id, the name agents store, stays the same.
display_nameThe model's name as a person reads it, for a picker.
capabilitiesWhat the model can do. TEXT_GENERATION to run a text agent at all; STRUCTURED_OUTPUT to run an agent whose output_format is JSON; EFFORT to accept an agent's effort; IMAGE_GENERATION to run an IMAGE agent; VISION and TOOL_CALLING are listed for later use.
max_input_tokensThe largest prompt the model accepts, in tokens.
max_output_tokensThe largest max_tokens an agent may set and still run on this model.
stateAVAILABLE models run. DEPRECATED and DISABLED ones do not, and an agent cannot be pointed at one — the platform takes a model out of service with this field, without a release.
tierA rough place on the speed-to-capability scale: FAST, BALANCED or POWERFUL.
platform_pricedWhether the platform has a price for what this model does — for an IMAGE_GENERATION model, a price for pictures in the unit its provider bills them by (per picture, or by tokens) — so a run on the platform's key can be charged. When it is false, a run on the platform's key is refused with MODEL_NOT_PRICED, and the model runs only on the account's own connection to its provider.
List ai_system_agents
The agents the platform ships, ready to copy into an account. Read one to see its instruction and settings; create an agent with source_system_agent set to its id to get a copy of your own. A copy does not follow later changes to the original.
query Parameters
page_sizeRows per page. Over the maximum is clamped, not rejected.
page_tokenOpaque token from a previous next_page_token. A token minted under a different order_by/filter is rejected.
skipRows to skip before the page (AIP-158). skip + page_size is capped at 10000; beyond that is OUT_OF_RANGE.
order_byComma-separated field [asc|desc], at most 3 keys. Default: display_name asc. Sortable: create_time, display_name.
filterAIP-160 subset (§8). Filterable: create_time, display_name. A field outside the list is INVALID_ARGUMENT.
List ai_system_agents › Responses
One page of ai_system_agents.
This page of ai_system_agents, in the requested order.
next_page_tokenOpaque. Absent or empty means this was the last page.
total_sizeRows in the whole filtered collection, not in this page.
Get ai_system_agent
The agents the platform ships, ready to copy into an account. Read one to see its instruction and settings; create an agent with source_system_agent set to its id to get a copy of your own. A copy does not follow later changes to the original.
path Parameters
ai_system_agent_idId of the parent ai_system_agent.
Headers
If-None-MatchA matching etag answers 304 with no body (§16).
Get ai_system_agent › Responses
The resource.
nameThe resource name (§5) — the identity of this resource, and the path that addresses it: websites/{website}/cms_pages/{cms_page}. It is the handle to store, not a human label.
idThe last segment of name on its own, for a client that needs to build a child URL. Unique inside its parent, never across the platform.
create_timeWhen the resource was created (RFC 3339, UTC).
update_timeWhen the resource last changed (RFC 3339, UTC).
etagVersion of the persisted state. Send it back in If-Match on Update or Delete and the write is rejected with ABORTED if anyone else changed the resource meanwhile (§14).
display_nameThe agent's name as a person reads it.
descriptionWhat the agent is for, in a sentence or two.
instruction_textThe agent's prompt template, with {{variable}} references. A copy of the agent starts from this text as version 1 of its own instruction.
instruction_versionWhich revision of instruction_text this is; it rises whenever the platform changes the text.
variablesThe variable names instruction_text references — the values a run of this agent is given.
preferred_model_idThe model a run uses when it does not name one.
allowed_model_idsThe only models a run may name; empty means any available model.
allowed_toolsTools the model may call. Always empty: tool calling is not available yet.
max_tokensThe most tokens one run may write.
effortHow hard the model is asked to think: LOW to MAX. Absent means the model's own default.
output_formatTEXT, JSON constrained by output_schema, or IMAGE — a picture of image_width by image_height.
output_schemaThe JSON Schema a JSON agent's answer follows. Present only when output_format is JSON.
image_widthThe width of the picture an IMAGE template asks for, in pixels. Present only on an IMAGE template.
image_heightThe height of the picture an IMAGE template asks for, in pixels. Present only on an IMAGE template.
connection_modeWhich connections a run may be paid through: ANY, BYOK_ONLY or MANAGED_ONLY.
max_attemptsHow many times a run is tried when the provider fails in a way worth retrying.
timeoutHow long one call to the provider may take, as a duration in seconds.
is_enabledWhether the platform offers this agent. One that is switched off cannot be copied.