Guardrail providers
Package: agentrouter.guardrails.v1 Service: GuardrailProvidersService
Endpoints
List guardrail providers
Changed in v0.4.0 (behaviour changes): A guardrail provider's credential is no longer accepted in its configuration. Creating or updating a provider with an Azure AI Content Safety "api_key", or an external service's "auth_token", inside the configuration now fails with an error naming the new SetGuardrailProviderSecret operation, which is the only way a credential enters. The credential is stored encrypted, the provider keeps only a reference to it, no read returns it -- providers now report whether one is stored, not what it is -- and calling the operation again rotates the credential in place. Providers created before this release keep working and stay editable: their credential no longer appears in any API response, and editing such a provider preserves it rather than dropping it, so it can only be replaced through SetGuardrailProviderSecret. Deleting a provider, or its project, destroys the credential with it.
Changed in v0.4.0 (behaviour changes): Listing and reading guardrail providers now requires either the "guardrail_providers.read" permission or a scope that grants guardrail reads, bringing provider reads into the same permission domain as the writes. Management API keys carrying the read, write, admin, guardrails_reader or guardrails_admin scope keep their access with no action needed, as do the Super Admin and Viewer roles and every console session. A key scoped only to an unrelated area -- audit logs, for example -- and any custom role that grants neither the new permission nor a guardrail read scope will now receive a permission error where a provider list or lookup previously succeeded. To restore access, add "guardrail_providers.read" to the custom role, or issue the key with a scope that includes guardrail reads.
Changed in v0.4.0 (security updates): A management API key scoped to an unrelated area can no longer enumerate a project's guardrail providers. Listing and reading providers required no permission and no scope at all, so any credential valid for the project could read every provider registered in it -- names, kinds and endpoints -- even though changing one had been restricted to administrators. Both operations are now gated. Callers holding a guardrail read scope are unaffected, which includes every console session, so this narrows the credentials that can reach provider configuration rather than closing the read to everyone without an explicit grant. No CVE; required a credential already valid for the project.
What it does: Returns the providers visible in the requested scope: the project's own instances plus the global rows. Catalog templates are omitted unless include_templates is set.
Request fields:
| Field | Required | Description |
|---|---|---|
customer_id | no | Owning customer scope; defaults to caller's session customer when empty. Global rows are visible in every scope. |
project_id | no | Owning project scope; defaults to caller's session project when empty. |
page | no | Cursor-pagination inputs. |
search | no | Optional substring search on provider name. |
enabled | no | When set, filter to enabled or disabled providers only. |
include_templates | no | When true, include template rows (is_template=true). |
Response fields:
| Field | Required | Description |
|---|---|---|
providers | no | Providers matching the request filters, one page's worth. |
page | no | Cursor-pagination outputs. |
total | no | Total count of matching providers across all pages. |
{"signatures":{"go":"c.GuardrailProviders().ListGuardrailProviders(ctx, \u0026guardrailsv1.ListGuardrailProvidersRequest{...})","python":"client.guardrailproviders.listguardrailproviders(...)","typescript":"client.guardrailproviders.listguardrailproviders({...})","cli":"tare api guardrails providers list","curl":"curl \"${AGENTROUTER_BASE_URL}/v1/customers/cust_01H.../projects/proj_01H.../guardrails/providers\" \\\n -H \"Authorization: Bearer ak-${AGENTROUTER_API_KEY}\""},"examples":{"go":"// No Go SDK wrapper for GuardrailProvidersService yet -- use the CLI or curl example below.","python":"# No Python SDK wrapper for GuardrailProvidersService yet -- use the CLI or curl example below.","typescript":"// No TypeScript SDK wrapper for GuardrailProvidersService yet -- use the CLI or curl example below.","cli":"tare api guardrails providers list","curl":"curl \"${AGENTROUTER_BASE_URL}/v1/customers/cust_01H.../projects/proj_01H.../guardrails/providers\" \\\n -H \"Authorization: Bearer ak-${AGENTROUTER_API_KEY}\""},"persona":"Admin","httpVerb":"GET","httpPath":"/v1/customers/{customer_id}/projects/{project_id}/guardrails/providers","slug":"list-guardrail-providers"}Get a guardrail provider
Changed in v0.4.0 (behaviour changes): A guardrail provider's credential is no longer accepted in its configuration. Creating or updating a provider with an Azure AI Content Safety "api_key", or an external service's "auth_token", inside the configuration now fails with an error naming the new SetGuardrailProviderSecret operation, which is the only way a credential enters. The credential is stored encrypted, the provider keeps only a reference to it, no read returns it -- providers now report whether one is stored, not what it is -- and calling the operation again rotates the credential in place. Providers created before this release keep working and stay editable: their credential no longer appears in any API response, and editing such a provider preserves it rather than dropping it, so it can only be replaced through SetGuardrailProviderSecret. Deleting a provider, or its project, destroys the credential with it.
Changed in v0.4.0 (behaviour changes): Listing and reading guardrail providers now requires either the "guardrail_providers.read" permission or a scope that grants guardrail reads, bringing provider reads into the same permission domain as the writes. Management API keys carrying the read, write, admin, guardrails_reader or guardrails_admin scope keep their access with no action needed, as do the Super Admin and Viewer roles and every console session. A key scoped only to an unrelated area -- audit logs, for example -- and any custom role that grants neither the new permission nor a guardrail read scope will now receive a permission error where a provider list or lookup previously succeeded. To restore access, add "guardrail_providers.read" to the custom role, or issue the key with a scope that includes guardrail reads.
Changed in v0.4.0 (security updates): A management API key scoped to an unrelated area can no longer enumerate a project's guardrail providers. Listing and reading providers required no permission and no scope at all, so any credential valid for the project could read every provider registered in it -- names, kinds and endpoints -- even though changing one had been restricted to administrators. Both operations are now gated. Callers holding a guardrail read scope are unaffected, which includes every console session, so this narrows the credentials that can reach provider configuration rather than closing the read to everyone without an explicit grant. No CVE; required a credential already valid for the project.
What it does: Returns a single provider by id, from the project's own instances or the global rows. Returns NOT_FOUND when no such provider is visible in the requested scope.
Request fields:
| Field | Required | Description |
|---|---|---|
customer_id | no | Owning customer scope; defaults to caller's session customer when empty. |
project_id | no | Owning project scope; defaults to caller's session project when empty. |
id | yes | Required: uuid of the provider to fetch. |
Response fields:
| Field | Required | Description |
|---|---|---|
provider | no | The requested guardrail provider. |
{"signatures":{"go":"c.GuardrailProviders().GetGuardrailProvider(ctx, \u0026guardrailsv1.GetGuardrailProviderRequest{...})","python":"client.guardrailproviders.getguardrailprovider(...)","typescript":"client.guardrailproviders.getguardrailprovider({...})","cli":"tare api guardrails providers get \u003cid\u003e","curl":"curl \"${AGENTROUTER_BASE_URL}/v1/customers/cust_01H.../projects/proj_01H.../guardrails/providers/01H...\" \\\n -H \"Authorization: Bearer ak-${AGENTROUTER_API_KEY}\""},"examples":{"go":"// No Go SDK wrapper for GuardrailProvidersService yet -- use the CLI or curl example below.","python":"# No Python SDK wrapper for GuardrailProvidersService yet -- use the CLI or curl example below.","typescript":"// No TypeScript SDK wrapper for GuardrailProvidersService yet -- use the CLI or curl example below.","cli":"tare api guardrails providers get \u003cid\u003e","curl":"curl \"${AGENTROUTER_BASE_URL}/v1/customers/cust_01H.../projects/proj_01H.../guardrails/providers/01H...\" \\\n -H \"Authorization: Bearer ak-${AGENTROUTER_API_KEY}\""},"persona":"Admin","httpVerb":"GET","httpPath":"/v1/customers/{customer_id}/projects/{project_id}/guardrails/providers/{id}","slug":"get-a-guardrail-provider"}Create a guardrail provider
Changed in v0.5.0 (behaviour changes): Creating or updating an externalservice guardrail provider now rejects, with INVALID_ARGUMENT, a config the data plane could not use: an unknown key or non-string value, a service_url that is not an absolute http or https URL or names a link-local or metadata address, a blank endpoint or one without a leading slash, a blank timeout or one outside 0-30s, or a ca_cert_pem over 8 KiB, over four certificates or holding anything else. Its rules need a raw.threshold above 0 and at most 1.
Changed in v0.5.0 (security updates): Creating or updating a guardrail provider now rejects the config key api_key_file, and the credential keys api_key and auth_token, under any spelling, with INVALID_ARGUMENT. A stored api_key_file is no longer delivered to the data plane: the management plane sets that key itself, so a caller could otherwise choose which credential file a provider reads.
Changed in v0.5.0 (new features): tare api guardrails providers create and update take the provider as --provider, a JSON object in the API's shape, so a guardrail provider can be registered and enabled from the CLI. The flag is required.
Changed in v0.4.0 (behaviour changes): A guardrail provider's credential is no longer accepted in its configuration. Creating or updating a provider with an Azure AI Content Safety "api_key", or an external service's "auth_token", inside the configuration now fails with an error naming the new SetGuardrailProviderSecret operation, which is the only way a credential enters. The credential is stored encrypted, the provider keeps only a reference to it, no read returns it -- providers now report whether one is stored, not what it is -- and calling the operation again rotates the credential in place. Providers created before this release keep working and stay editable: their credential no longer appears in any API response, and editing such a provider preserves it rather than dropping it, so it can only be replaced through SetGuardrailProviderSecret. Deleting a provider, or its project, destroys the credential with it.
Changed in v0.4.0 (new features): Creating or updating a guardrail provider now fails with a clear message when the provider could never run: an Azure AI Content Safety provider must carry an endpoint that is an absolute http(s) URL, alongside the existing checks on provider kind and on an external service's declared checks. Such a provider used to be saved and shipped, and then quietly skipped by the gateway, so every rule bound to it stopped enforcing with nothing to see. Existing providers are untouched: only a write that actually changes the configuration is checked, so renaming or disabling one still works even if its stored configuration would not pass.
What it does: Registers a new provider instance in the requested scope. Any accepted kind may be created, including the kinds the catalog templates use. Returns ALREADY_EXISTS when the name is taken in that scope, and INVALID_ARGUMENT for an unaccepted kind, a configuration the kind cannot be built from, or a credential in config.
Request fields:
| Field | Required | Description |
|---|---|---|
customer_id | no | Owning customer scope; defaults to caller's session customer when empty. |
project_id | no | Owning project scope; defaults to caller's session project when empty. |
provider | yes | Required: provider to create. id must be absent or empty (server-assigned). |
Response fields:
| Field | Required | Description |
|---|---|---|
provider | no | The created provider with server-assigned fields populated. |
{"signatures":{"go":"c.GuardrailProviders().CreateGuardrailProvider(ctx, \u0026guardrailsv1.CreateGuardrailProviderRequest{...})","python":"client.guardrailproviders.createguardrailprovider(...)","typescript":"client.guardrailproviders.createguardrailprovider({...})","cli":"tare api guardrails providers create --provider $PROVIDER","curl":"curl -X POST \"${AGENTROUTER_BASE_URL}/v1/customers/cust_01H.../projects/proj_01H.../guardrails/providers\" \\\n -H \"Authorization: Bearer ak-${AGENTROUTER_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"provider\": {}\n }'"},"examples":{"go":"// No Go SDK wrapper for GuardrailProvidersService yet -- use the CLI or curl example below.","python":"# No Python SDK wrapper for GuardrailProvidersService yet -- use the CLI or curl example below.","typescript":"// No TypeScript SDK wrapper for GuardrailProvidersService yet -- use the CLI or curl example below.","cli":"tare api guardrails providers create --provider $PROVIDER","curl":"curl -X POST \"${AGENTROUTER_BASE_URL}/v1/customers/cust_01H.../projects/proj_01H.../guardrails/providers\" \\\n -H \"Authorization: Bearer ak-${AGENTROUTER_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"provider\": {}\n }'"},"persona":"Admin","httpVerb":"POST","httpPath":"/v1/customers/{customer_id}/projects/{project_id}/guardrails/providers","slug":"create-a-guardrail-provider"}Update a guardrail provider
Changed in v0.5.0 (behaviour changes): Creating or updating an externalservice guardrail provider now rejects, with INVALID_ARGUMENT, a config the data plane could not use: an unknown key or non-string value, a service_url that is not an absolute http or https URL or names a link-local or metadata address, a blank endpoint or one without a leading slash, a blank timeout or one outside 0-30s, or a ca_cert_pem over 8 KiB, over four certificates or holding anything else. Its rules need a raw.threshold above 0 and at most 1.
Changed in v0.5.0 (security updates): Creating or updating a guardrail provider now rejects the config key api_key_file, and the credential keys api_key and auth_token, under any spelling, with INVALID_ARGUMENT. A stored api_key_file is no longer delivered to the data plane: the management plane sets that key itself, so a caller could otherwise choose which credential file a provider reads.
Changed in v0.5.0 (new features): tare api guardrails providers create and update take the provider as --provider, a JSON object in the API's shape, so a guardrail provider can be registered and enabled from the CLI. The flag is required.
Changed in v0.4.0 (behaviour changes): A guardrail provider's credential is no longer accepted in its configuration. Creating or updating a provider with an Azure AI Content Safety "api_key", or an external service's "auth_token", inside the configuration now fails with an error naming the new SetGuardrailProviderSecret operation, which is the only way a credential enters. The credential is stored encrypted, the provider keeps only a reference to it, no read returns it -- providers now report whether one is stored, not what it is -- and calling the operation again rotates the credential in place. Providers created before this release keep working and stay editable: their credential no longer appears in any API response, and editing such a provider preserves it rather than dropping it, so it can only be replaced through SetGuardrailProviderSecret. Deleting a provider, or its project, destroys the credential with it.
Changed in v0.4.0 (new features): Creating or updating a guardrail provider now fails with a clear message when the provider could never run: an Azure AI Content Safety provider must carry an endpoint that is an absolute http(s) URL, alongside the existing checks on provider kind and on an external service's declared checks. Such a provider used to be saved and shipped, and then quietly skipped by the gateway, so every rule bound to it stopped enforcing with nothing to see. Existing providers are untouched: only a write that actually changes the configuration is checked, so renaming or disabling one still works even if its stored configuration would not pass.
What it does: Updates mutable fields of a user-defined provider. Omitted/empty scalar string fields leave the existing value untouched. Enum fields set to *_UNSPECIFIED leave the existing value untouched. Absent message fields (config) leave the existing value untouched; a present config Struct REPLACES the stored configuration wholesale (no deep merge). Returns PERMISSION_DENIED for a global row or a catalog template (both are read-only), and NOT_FOUND when no such provider is visible in the requested scope.
Request fields:
| Field | Required | Description |
|---|---|---|
customer_id | no | Owning customer scope; defaults to caller's session customer when empty. |
project_id | no | Owning project scope; defaults to caller's session project when empty. |
provider | yes | Required: provider to update. provider.id must be set. Partial update semantics: omitted/empty scalar string fields leave the existing value untouched; enum fields set to *_UNSPECIFIED leave the existing value untouched; absent message fields (config) leave the existing value untouched; a present config Struct REPLACES the stored configuration wholesale (no deep merge). |
Response fields:
| Field | Required | Description |
|---|---|---|
provider | no | The updated provider with server-assigned fields populated. |
{"signatures":{"go":"c.GuardrailProviders().UpdateGuardrailProvider(ctx, \u0026guardrailsv1.UpdateGuardrailProviderRequest{...})","python":"client.guardrailproviders.updateguardrailprovider(...)","typescript":"client.guardrailproviders.updateguardrailprovider({...})","cli":"tare api guardrails providers update --provider $PROVIDER","curl":"curl -X PATCH \"${AGENTROUTER_BASE_URL}/v1/customers/cust_01H.../projects/proj_01H.../guardrails/providers/01H...\" \\\n -H \"Authorization: Bearer ak-${AGENTROUTER_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"provider\": {}\n }'"},"examples":{"go":"// No Go SDK wrapper for GuardrailProvidersService yet -- use the CLI or curl example below.","python":"# No Python SDK wrapper for GuardrailProvidersService yet -- use the CLI or curl example below.","typescript":"// No TypeScript SDK wrapper for GuardrailProvidersService yet -- use the CLI or curl example below.","cli":"tare api guardrails providers update --provider $PROVIDER","curl":"curl -X PATCH \"${AGENTROUTER_BASE_URL}/v1/customers/cust_01H.../projects/proj_01H.../guardrails/providers/01H...\" \\\n -H \"Authorization: Bearer ak-${AGENTROUTER_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"provider\": {}\n }'"},"persona":"Admin","httpVerb":"PATCH","httpPath":"/v1/customers/{customer_id}/projects/{project_id}/guardrails/providers/{provider.id}","slug":"update-a-guardrail-provider"}Delete a guardrail provider
Changed in v0.4.0 (behaviour changes): A guardrail provider's credential is no longer accepted in its configuration. Creating or updating a provider with an Azure AI Content Safety "api_key", or an external service's "auth_token", inside the configuration now fails with an error naming the new SetGuardrailProviderSecret operation, which is the only way a credential enters. The credential is stored encrypted, the provider keeps only a reference to it, no read returns it -- providers now report whether one is stored, not what it is -- and calling the operation again rotates the credential in place. Providers created before this release keep working and stay editable: their credential no longer appears in any API response, and editing such a provider preserves it rather than dropping it, so it can only be replaced through SetGuardrailProviderSecret. Deleting a provider, or its project, destroys the credential with it.
What it does: Soft-deletes a user-defined provider (sets deleted_at; the row disappears from List/Get). Historical trigger records referencing this provider REMAIN queryable. Returns PERMISSION_DENIED for a global row or a catalog template (both are read-only), and NOT_FOUND when no such provider is visible in the requested scope.
Request fields:
| Field | Required | Description |
|---|---|---|
customer_id | no | Owning customer scope; defaults to caller's session customer when empty. |
project_id | no | Owning project scope; defaults to caller's session project when empty. |
id | yes | Required: uuid of the provider to delete. |
{"signatures":{"go":"c.GuardrailProviders().DeleteGuardrailProvider(ctx, \u0026guardrailsv1.DeleteGuardrailProviderRequest{...})","python":"client.guardrailproviders.deleteguardrailprovider(...)","typescript":"client.guardrailproviders.deleteguardrailprovider({...})","cli":"tare api guardrails providers delete \u003cid\u003e","curl":"curl -X DELETE \"${AGENTROUTER_BASE_URL}/v1/customers/cust_01H.../projects/proj_01H.../guardrails/providers/01H...\" \\\n -H \"Authorization: Bearer ak-${AGENTROUTER_API_KEY}\""},"examples":{"go":"// No Go SDK wrapper for GuardrailProvidersService yet -- use the CLI or curl example below.","python":"# No Python SDK wrapper for GuardrailProvidersService yet -- use the CLI or curl example below.","typescript":"// No TypeScript SDK wrapper for GuardrailProvidersService yet -- use the CLI or curl example below.","cli":"tare api guardrails providers delete \u003cid\u003e","curl":"curl -X DELETE \"${AGENTROUTER_BASE_URL}/v1/customers/cust_01H.../projects/proj_01H.../guardrails/providers/01H...\" \\\n -H \"Authorization: Bearer ak-${AGENTROUTER_API_KEY}\""},"persona":"Admin","httpVerb":"DELETE","httpPath":"/v1/customers/{customer_id}/projects/{project_id}/guardrails/providers/{id}","slug":"delete-a-guardrail-provider"}Set a guardrail provider credential
Changed in v0.4.0 (behaviour changes): A guardrail provider's credential is no longer accepted in its configuration. Creating or updating a provider with an Azure AI Content Safety "api_key", or an external service's "auth_token", inside the configuration now fails with an error naming the new SetGuardrailProviderSecret operation, which is the only way a credential enters. The credential is stored encrypted, the provider keeps only a reference to it, no read returns it -- providers now report whether one is stored, not what it is -- and calling the operation again rotates the credential in place. Providers created before this release keep working and stay editable: their credential no longer appears in any API response, and editing such a provider preserves it rather than dropping it, so it can only be replaced through SetGuardrailProviderSecret. Deleting a provider, or its project, destroys the credential with it.
What it does: Stores the credential a provider authenticates to its backing service with. This is the ONLY way a credential enters the system: it is never accepted in GuardrailProvider.config. Write-only. The value is encrypted at rest, the provider row keeps only a reference to it, and no read path -- List, Get, or the data-plane configuration -- ever returns it. GuardrailProvider.has_api_key is all a reader learns. Calling it again ROTATES: the stored credential is replaced in place and the provider keeps its id, its configuration and every rule bound to it. There is no un-set; deleting the provider's project destroys the stored credential. The operation is audit-logged. The audit entry records who set a credential on which provider, never the value. Returns NOT_FOUND when no such provider is visible in the requested scope, and PERMISSION_DENIED for a global row or a catalog template (both are read-only; a template is copied into an instance before it is used).
Request fields:
| Field | Required | Description |
|---|---|---|
customer_id | no | Owning customer scope; defaults to caller's session customer when empty. |
project_id | no | Owning project scope; defaults to caller's session project when empty. |
id | yes | Required: uuid of the provider to set the credential on. |
api_key | yes | Required: the credential, in plaintext. Write-only -- it is encrypted before it is stored and is never readable back through this API. Empty is rejected; this RPC sets a credential, it does not clear one. |
Response fields:
| Field | Required | Description |
|---|---|---|
provider | no | The provider, with has_api_key now true. Carries no credential material. |
{"signatures":{"go":"c.GuardrailProviders().SetGuardrailProviderSecret(ctx, \u0026guardrailsv1.SetGuardrailProviderSecretRequest{...})","python":"client.guardrailproviders.setguardrailprovidersecret(...)","typescript":"client.guardrailproviders.setguardrailprovidersecret({...})","cli":"tare api guardrails providers set-secret \u003cid\u003e --api-key $API_KEY","curl":"curl -X POST \"${AGENTROUTER_BASE_URL}/v1/customers/cust_01H.../projects/proj_01H.../guardrails/providers/01H.../secret\" \\\n -H \"Authorization: Bearer ak-${AGENTROUTER_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"api_key\": \"...\"\n }'"},"examples":{"go":"// No Go SDK wrapper for GuardrailProvidersService yet -- use the CLI or curl example below.","python":"# No Python SDK wrapper for GuardrailProvidersService yet -- use the CLI or curl example below.","typescript":"// No TypeScript SDK wrapper for GuardrailProvidersService yet -- use the CLI or curl example below.","cli":"tare api guardrails providers set-secret \u003cid\u003e --api-key $API_KEY","curl":"curl -X POST \"${AGENTROUTER_BASE_URL}/v1/customers/cust_01H.../projects/proj_01H.../guardrails/providers/01H.../secret\" \\\n -H \"Authorization: Bearer ak-${AGENTROUTER_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"api_key\": \"...\"\n }'"},"persona":"Admin","httpVerb":"POST","httpPath":"/v1/customers/{customer_id}/projects/{project_id}/guardrails/providers/{id}/secret","slug":"set-a-guardrail-provider-credential"}