> For the complete documentation index, see [llms.txt](https://docs.otari.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.otari.ai/otari/for-integrators/api-reference/tool-settings.md).

# Tool settings

## Get Tool Settings

> Return the effective tool/guardrail settings for the dashboard.\
> \
> Authentication only on the router: the role decides \*how much\* rather than\
> whether, so this is not the deployment-wide gate \`\`require\_deployment\_operator\`\`\
> names. A header master key is the deployment credential and reads everything;\
> a session reads everything only while it operates the deployment, and\
> otherwise gets the fields without the service endpoints in them.

```json
{"openapi":"3.1.0","info":{"title":"otari","version":"0.33.0"},"security":[{"ApiKeyAuth":[]},{"XApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Enter your API key here (sent as Otari-Key header).","in":"header","name":"Otari-Key","type":"apiKey"},"XApiKeyAuth":{"description":"Anthropic-native clients send credentials here (no Bearer prefix).","in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"ToolSettingsResponse":{"description":"The effective value of every editable tool/guardrail field.","properties":{"fields":{"items":{"$ref":"#/components/schemas/ToolSettingField"},"title":"Fields","type":"array"},"sandbox_credential":{"anyOf":[{"$ref":"#/components/schemas/SandboxCredentialPublic"},{"type":"null"}],"description":"The key a hosted sandbox_provider leases with. Null for the protocol provider, which takes none, and for a reader who does not operate the deployment."},"sandbox_provider":{"anyOf":[{"$ref":"#/components/schemas/SandboxProvider"},{"type":"null"}],"description":"What runs generated code: 'protocol' (a sandbox at sandbox_url) or 'e2b'. Set at startup, not editable here. Null for a reader who does not operate the deployment."}},"required":["fields"],"title":"ToolSettingsResponse","type":"object"},"ToolSettingField":{"description":"One editable tool/guardrail field surfaced to the dashboard.","properties":{"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"key":{"title":"Key","type":"string"},"options":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Options"},"service":{"enum":["web_search","sandbox","guardrails"],"title":"Service","type":"string"},"type":{"enum":["url","str","int","bool"],"title":"Type","type":"string"},"value":{"anyOf":[{"type":"boolean"},{"type":"integer"},{"type":"string"},{"type":"null"}],"title":"Value"}},"required":["key","service","type","value"],"title":"ToolSettingField","type":"object"},"SandboxCredentialPublic":{"description":"Where the key a hosted sandbox provider leases with comes from. Never the key itself.","properties":{"env_var":{"description":"The environment variable a deployment that stores no key is read from.","title":"Env Var","type":"string"},"last4":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The key's last four characters, to tell keys apart.","title":"Last4"},"source":{"anyOf":[{"enum":["stored","environment"],"type":"string"},{"type":"null"}],"description":"'stored' for a key set here, which wins; 'environment' for the provider's own environment variable; null when there is neither and code execution fails until one is set.","title":"Source"}},"required":["source","env_var"],"title":"SandboxCredentialPublic","type":"object"},"SandboxProvider":{"description":"What runs the code a code-execution tool call asks for, chosen per deployment.\n\nValues are read without regard to case or surrounding whitespace.","enum":["protocol","e2b"],"title":"SandboxProvider","type":"string"}}},"paths":{"/api/v1/tool-settings":{"get":{"description":"Return the effective tool/guardrail settings for the dashboard.\n\nAuthentication only on the router: the role decides *how much* rather than\nwhether, so this is not the deployment-wide gate ``require_deployment_operator``\nnames. A header master key is the deployment credential and reads everything;\na session reads everything only while it operates the deployment, and\notherwise gets the fields without the service endpoints in them.","operationId":"tool-settings-get_tool_settings","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolSettingsResponse"}}},"description":"Successful Response"}},"summary":"Get Tool Settings","tags":["tool-settings"]}}}}
```

## Update Tool Settings

> Persist and apply tool/guardrail setting changes.\
> \
> Uses \`\`model\_fields\_set\`\` so an explicit \`\`null\`\` clears a field while an\
> omitted field is left unchanged. Operator-gated.

```json
{"openapi":"3.1.0","info":{"title":"otari","version":"0.33.0"},"security":[{"ApiKeyAuth":[]},{"XApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Enter your API key here (sent as Otari-Key header).","in":"header","name":"Otari-Key","type":"apiKey"},"XApiKeyAuth":{"description":"Anthropic-native clients send credentials here (no Bearer prefix).","in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"UpdateToolSettingsRequest":{"description":"Change one or more tool settings. Omitted fields are left unchanged; an\nexplicit ``null`` clears a field back to the configured env/YAML default.","properties":{"code_execution_executor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code Execution Executor"},"guardrails_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Guardrails Url"},"sandbox_purpose_hint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sandbox Purpose Hint"},"sandbox_session_image":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sandbox Session Image"},"sandbox_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sandbox Url"},"web_fetch_default_tool":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A fetch instance, or 'builtin_fetch'.","title":"Web Fetch Default Tool"},"web_search_default_tool":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A search instance whose provider any-search serves, or 'none' to turn off the deployment's own in-loop search, which an organization key still serves.","title":"Web Search Default Tool"},"web_search_engines":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Web Search Engines"},"web_search_extract":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Web Search Extract"},"web_search_intercept":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Web Search Intercept"},"web_search_max_calls":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"title":"Web Search Max Calls"},"web_search_max_results":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"title":"Web Search Max Results"},"web_search_purpose_hint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Web Search Purpose Hint"},"web_search_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Web Search Url"}},"title":"UpdateToolSettingsRequest","type":"object"},"ToolSettingsResponse":{"description":"The effective value of every editable tool/guardrail field.","properties":{"fields":{"items":{"$ref":"#/components/schemas/ToolSettingField"},"title":"Fields","type":"array"},"sandbox_credential":{"anyOf":[{"$ref":"#/components/schemas/SandboxCredentialPublic"},{"type":"null"}],"description":"The key a hosted sandbox_provider leases with. Null for the protocol provider, which takes none, and for a reader who does not operate the deployment."},"sandbox_provider":{"anyOf":[{"$ref":"#/components/schemas/SandboxProvider"},{"type":"null"}],"description":"What runs generated code: 'protocol' (a sandbox at sandbox_url) or 'e2b'. Set at startup, not editable here. Null for a reader who does not operate the deployment."}},"required":["fields"],"title":"ToolSettingsResponse","type":"object"},"ToolSettingField":{"description":"One editable tool/guardrail field surfaced to the dashboard.","properties":{"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"key":{"title":"Key","type":"string"},"options":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Options"},"service":{"enum":["web_search","sandbox","guardrails"],"title":"Service","type":"string"},"type":{"enum":["url","str","int","bool"],"title":"Type","type":"string"},"value":{"anyOf":[{"type":"boolean"},{"type":"integer"},{"type":"string"},{"type":"null"}],"title":"Value"}},"required":["key","service","type","value"],"title":"ToolSettingField","type":"object"},"SandboxCredentialPublic":{"description":"Where the key a hosted sandbox provider leases with comes from. Never the key itself.","properties":{"env_var":{"description":"The environment variable a deployment that stores no key is read from.","title":"Env Var","type":"string"},"last4":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The key's last four characters, to tell keys apart.","title":"Last4"},"source":{"anyOf":[{"enum":["stored","environment"],"type":"string"},{"type":"null"}],"description":"'stored' for a key set here, which wins; 'environment' for the provider's own environment variable; null when there is neither and code execution fails until one is set.","title":"Source"}},"required":["source","env_var"],"title":"SandboxCredentialPublic","type":"object"},"SandboxProvider":{"description":"What runs the code a code-execution tool call asks for, chosen per deployment.\n\nValues are read without regard to case or surrounding whitespace.","enum":["protocol","e2b"],"title":"SandboxProvider","type":"string"},"HTTPValidationError":{"properties":{"code":{"const":"invalid_request","description":"Stable error code, also sent as the Otari-Error-Code header.","title":"Code","type":"string"},"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}},"paths":{"/api/v1/tool-settings":{"patch":{"description":"Persist and apply tool/guardrail setting changes.\n\nUses ``model_fields_set`` so an explicit ``null`` clears a field while an\nomitted field is left unchanged. Operator-gated.","operationId":"tool-settings-update_tool_settings","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateToolSettingsRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolSettingsResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Update Tool Settings","tags":["tool-settings"]}}}}
```

## List Builtin Guardrails

> List the guardrails this gateway can run itself, for the form that defines one.\
> \
> Every guardrail \`\`any\_guardrail\`\` reaches over a hosted API, with the\
> constructor and per-call arguments each one takes, so a guardrail is\
> configured by picking it and filling typed fields. It is not the whole\
> library: a guardrail that works by holding model weights in the process\
> running it belongs in the guardrails service the profiles read beside this one\
> describes, not here. A parameter names the environment variable that fills it\
> where one exists, and \`\`requirement\_groups\`\` carries the constraints satisfied\
> by any of several parameters, which no single required flag can state. This is\
> the counterpart of\
> \`\`GET /api/v1/providers/catalog\`\`: the same picker, for a guardrail rather\
> than a provider, and on the same gate that one takes.\
> \
> Reaches no service, so there is no unavailable state to report: the answer is\
> a property of the installed \`\`any\_guardrail\`\`, not of any deployment's state.\
> \
> On the catalog router rather than the operator one beside it, because the\
> form this feeds belongs to an organization and is filled by an owner or\
> admin, who reaches no operator route. So it is readable without\
> deployment-wide standing, by a dashboard session and by any API key alike.\
> What it publishes carries no deployment state to withhold: the same bytes on\
> every deployment of the same build, and a parameter's environment variable is\
> a name, never whether that name is set.\
> \
> The profiles read next door keeps the stricter gate, and the difference is\
> reach rather than audience. That one dials \`\`guardrails\_url\`\`, so admitting a\
> key there would let a workspace credential probe the deployment's own\
> service. This one dials nothing.

```json
{"openapi":"3.1.0","info":{"title":"otari","version":"0.33.0"},"security":[{"ApiKeyAuth":[]},{"XApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Enter your API key here (sent as Otari-Key header).","in":"header","name":"Otari-Key","type":"apiKey"},"XApiKeyAuth":{"description":"Anthropic-native clients send credentials here (no Bearer prefix).","in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"BuiltInGuardrailCatalog":{"description":"The guardrails this gateway can build and call itself.","properties":{"guardrails":{"items":{"$ref":"#/components/schemas/BuiltInGuardrailSpec"},"title":"Guardrails","type":"array"}},"title":"BuiltInGuardrailCatalog","type":"object"},"BuiltInGuardrailSpec":{"description":"One guardrail this gateway can construct and run itself.\n\nUpstream's own metadata model, extended rather than copied, so a field it adds\nis carried instead of waiting on an edit here. The four taxonomy enums document\nthemselves in the published schema, which is why almost nothing below restates\nwhat a field name and its type already say; the descriptions that remain are on\nthe answers only this gateway can give.\n\nInheriting also takes upstream's field serializers, which sort every set-valued\nfield on the way out, so the JSON is stable across calls without sorting anything\nhere.","properties":{"alternate_backends":{"items":{"type":"string"},"title":"Alternate Backends","type":"array"},"backend":{"$ref":"#/components/schemas/BackendType"},"categories":{"items":{"type":"string"},"title":"Categories","type":"array"},"create_parameters":{"description":"Constructor arguments, which is where a vendor API key and an endpoint live","items":{"$ref":"#/components/schemas/GuardrailParameterSpec"},"title":"Create Parameters","type":"array"},"default_license":{"title":"Default License","type":"string"},"description":{"title":"Description","type":"string"},"display_name":{"title":"Display Name","type":"string"},"guardrail_name":{"description":"The any-guardrail class, and the name a stored guardrail selects","title":"Guardrail Name","type":"string"},"multilingual":{"default":false,"title":"Multilingual","type":"boolean"},"multimodal":{"default":false,"title":"Multimodal","type":"boolean"},"optional_validate_kwargs":{"items":{"type":"string"},"title":"Optional Validate Kwargs","type":"array"},"output_shapes":{"items":{"type":"string"},"title":"Output Shapes","type":"array"},"primary_category":{"$ref":"#/components/schemas/GuardrailCategory"},"required_validate_kwargs":{"items":{"type":"string"},"title":"Required Validate Kwargs","type":"array"},"requirement_groups":{"description":"One-of constraints that no single parameter's required flag can express. At least one member of each group must be supplied, or one of the environment variables that satisfies it","items":{"$ref":"#/components/schemas/RequirementGroup"},"title":"Requirement Groups","type":"array"},"requires_api_key":{"default":false,"title":"Requires Api Key","type":"boolean"},"stages":{"items":{"type":"string"},"title":"Stages","type":"array"},"supports_batch":{"default":false,"description":"Whether several inputs run as one real batched call, not a per-item loop","title":"Supports Batch","type":"boolean"},"validate_parameters":{"description":"Per-call arguments, sent with the text on every check","items":{"$ref":"#/components/schemas/GuardrailParameterSpec"},"title":"Validate Parameters","type":"array"},"variant_licenses":{"items":{"additionalProperties":{"type":"string"},"type":"object"},"title":"Variant Licenses","type":"array"},"vendor":{"title":"Vendor","type":"string"}},"required":["description","display_name","categories","primary_category","stages","output_shapes","backend","vendor","default_license","guardrail_name"],"title":"BuiltInGuardrailSpec","type":"object"},"BackendType":{"description":"How a guardrail executes.","enum":["local_encoder","local_decoder","hosted_api","library_wrapped"],"title":"BackendType","type":"string"},"GuardrailParameterSpec":{"description":"One ``validate_kwargs`` key a profile accepts, typed for a form control.","properties":{"choices":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"description":"Allowed values for an enum parameter","title":"Choices"},"default":{"description":"The signature default, or null when there is none","title":"Default"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"One-line help text from the guardrail's docstring","title":"Description"},"env_var":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The environment variable that supplies this parameter when no value is stored, so a form can offer that instead of demanding a credential the deployment already has","title":"Env Var"},"name":{"description":"The keyword argument's name, as it is sent in validate_kwargs","title":"Name","type":"string"},"required":{"description":"Whether a value must be supplied for the guardrail to run. Folds together the signature having no default and upstream's effectively-required flag, which covers a parameter that defaults to a value the guardrail then refuses to run without","title":"Required","type":"boolean"},"secret":{"default":false,"description":"Whether the value is a credential, so a form masks it and never echoes it back","title":"Secret","type":"boolean"},"storable":{"default":true,"description":"Whether a saved value can stand in for this parameter. False for a secret whose type is json, which upstream uses for a live object (an authenticated SDK client or session) that cannot be written down. A form offers no field for one","title":"Storable","type":"boolean"},"type":{"description":"Value shape, so a form can render the matching control","enum":["string","integer","number","boolean","enum","json"],"title":"Type","type":"string"}},"required":["name","type","required"],"title":"GuardrailParameterSpec","type":"object"},"GuardrailCategory":{"description":"What a guardrail is designed to detect (a guardrail may span several).","enum":["prompt_injection","content_safety","toxicity","pii","hallucination","off_topic","bias","tool_use","general_judge"],"title":"GuardrailCategory","type":"string"},"RequirementGroup":{"description":"A guardrail-level \"at least one of these must be provided\" constraint.\n\nSome guardrails require *a value* that no single parameter's :attr:`ParameterSpec.required`\nor :attr:`ParameterSpec.effectively_required` can express, because it can be satisfied by any\nof several parameters — e.g. watsonx needs a ``project_id`` *or* a ``space_id``. Each group\nnames the interchangeable parameters (and any environment variables that also satisfy it); a\nconfig UI should require the user to supply at least one member.","properties":{"description":{"title":"Description","type":"string"},"env_vars":{"default":[],"items":{"type":"string"},"title":"Env Vars","type":"array"},"parameters":{"items":{"type":"string"},"title":"Parameters","type":"array"}},"required":["description","parameters"],"title":"RequirementGroup","type":"object"}}},"paths":{"/api/v1/tool-settings/guardrails/catalog":{"get":{"description":"List the guardrails this gateway can run itself, for the form that defines one.\n\nEvery guardrail ``any_guardrail`` reaches over a hosted API, with the\nconstructor and per-call arguments each one takes, so a guardrail is\nconfigured by picking it and filling typed fields. It is not the whole\nlibrary: a guardrail that works by holding model weights in the process\nrunning it belongs in the guardrails service the profiles read beside this one\ndescribes, not here. A parameter names the environment variable that fills it\nwhere one exists, and ``requirement_groups`` carries the constraints satisfied\nby any of several parameters, which no single required flag can state. This is\nthe counterpart of\n``GET /api/v1/providers/catalog``: the same picker, for a guardrail rather\nthan a provider, and on the same gate that one takes.\n\nReaches no service, so there is no unavailable state to report: the answer is\na property of the installed ``any_guardrail``, not of any deployment's state.\n\nOn the catalog router rather than the operator one beside it, because the\nform this feeds belongs to an organization and is filled by an owner or\nadmin, who reaches no operator route. So it is readable without\ndeployment-wide standing, by a dashboard session and by any API key alike.\nWhat it publishes carries no deployment state to withhold: the same bytes on\nevery deployment of the same build, and a parameter's environment variable is\na name, never whether that name is set.\n\nThe profiles read next door keeps the stricter gate, and the difference is\nreach rather than audience. That one dials ``guardrails_url``, so admitting a\nkey there would let a workspace credential probe the deployment's own\nservice. This one dials nothing.","operationId":"tool-settings-list_builtin_guardrails","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuiltInGuardrailCatalog"}}},"description":"Successful Response"}},"summary":"List Builtin Guardrails","tags":["tool-settings"]}}}}
```

## List Guardrail Profiles

> List the guardrail profiles this deployment's guardrails service has built.\
> \
> What an organization guardrail's \`\`profile\`\` may name, with the\
> \`\`validate\_kwargs\`\` each one accepts, so the dashboard offers a picker and\
> typed fields instead of a free-text box beside an unrendered dict. The\
> profiles come from the service itself and the parameter schemas from the\
> \`\`any\_guardrail\`\` registry; neither is a list kept in this repository. See\
> \`gateway.services.guardrail\_catalog\`.\
> \
> Reports \`\`available: false\`\` with a reason rather than an error when the\
> service is unconfigured, unreachable, or older than its \`\`/profiles\`\`\
> endpoint, because a guardrails outage must not also break the page that\
> configures guardrails.\
> \
> Read against \`\`guardrails\_url\`\`, which is the deployment's own service. An\
> entry that carries an endpoint of its own is not probed: that URL is\
> caller-supplied and fetching it here would make this a way to have the\
> gateway request an address of the caller's choosing.\
> \
> Not on \`\`verify\_catalog\_reader\`\`, despite being a catalog read: that gate\
> admits any API key to the deployment-describing reads, and admitting a key\
> here would let any workspace credential dial the deployment's guardrails\
> service. This is a management read, so it takes the router's own gate.

```json
{"openapi":"3.1.0","info":{"title":"otari","version":"0.33.0"},"security":[{"ApiKeyAuth":[]},{"XApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Enter your API key here (sent as Otari-Key header).","in":"header","name":"Otari-Key","type":"apiKey"},"XApiKeyAuth":{"description":"Anthropic-native clients send credentials here (no Bearer prefix).","in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"GuardrailCatalog":{"description":"The profiles a guardrail entry may name, or why they could not be listed.","properties":{"available":{"description":"Whether the guardrails service answered with its profiles","title":"Available","type":"boolean"},"profiles":{"items":{"$ref":"#/components/schemas/GuardrailProfileSpec"},"title":"Profiles","type":"array"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Why the catalog is unavailable, in terms a tenant can act on","title":"Reason"}},"required":["available"],"title":"GuardrailCatalog","type":"object"},"GuardrailProfileSpec":{"description":"One profile the operator's guardrails service has built.","properties":{"guardrail":{"description":"The any-guardrail class the profile is built from","title":"Guardrail","type":"string"},"model_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The model the operator pinned, when they pinned one","title":"Model Id"},"parameters":{"description":"The validate_kwargs this profile accepts","items":{"$ref":"#/components/schemas/GuardrailParameterSpec"},"title":"Parameters","type":"array"},"parameters_known":{"description":"False when this gateway's any-guardrail is older than the service's and has no schema for that class. The profile is still selectable; only its typed fields are missing","title":"Parameters Known","type":"boolean"},"profile":{"description":"The name a guardrail entry puts in its profile field","title":"Profile","type":"string"}},"required":["profile","guardrail","parameters_known"],"title":"GuardrailProfileSpec","type":"object"},"GuardrailParameterSpec":{"description":"One ``validate_kwargs`` key a profile accepts, typed for a form control.","properties":{"choices":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"description":"Allowed values for an enum parameter","title":"Choices"},"default":{"description":"The signature default, or null when there is none","title":"Default"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"One-line help text from the guardrail's docstring","title":"Description"},"env_var":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The environment variable that supplies this parameter when no value is stored, so a form can offer that instead of demanding a credential the deployment already has","title":"Env Var"},"name":{"description":"The keyword argument's name, as it is sent in validate_kwargs","title":"Name","type":"string"},"required":{"description":"Whether a value must be supplied for the guardrail to run. Folds together the signature having no default and upstream's effectively-required flag, which covers a parameter that defaults to a value the guardrail then refuses to run without","title":"Required","type":"boolean"},"secret":{"default":false,"description":"Whether the value is a credential, so a form masks it and never echoes it back","title":"Secret","type":"boolean"},"storable":{"default":true,"description":"Whether a saved value can stand in for this parameter. False for a secret whose type is json, which upstream uses for a live object (an authenticated SDK client or session) that cannot be written down. A form offers no field for one","title":"Storable","type":"boolean"},"type":{"description":"Value shape, so a form can render the matching control","enum":["string","integer","number","boolean","enum","json"],"title":"Type","type":"string"}},"required":["name","type","required"],"title":"GuardrailParameterSpec","type":"object"}}},"paths":{"/api/v1/tool-settings/guardrails/profiles":{"get":{"description":"List the guardrail profiles this deployment's guardrails service has built.\n\nWhat an organization guardrail's ``profile`` may name, with the\n``validate_kwargs`` each one accepts, so the dashboard offers a picker and\ntyped fields instead of a free-text box beside an unrendered dict. The\nprofiles come from the service itself and the parameter schemas from the\n``any_guardrail`` registry; neither is a list kept in this repository. See\n`gateway.services.guardrail_catalog`.\n\nReports ``available: false`` with a reason rather than an error when the\nservice is unconfigured, unreachable, or older than its ``/profiles``\nendpoint, because a guardrails outage must not also break the page that\nconfigures guardrails.\n\nRead against ``guardrails_url``, which is the deployment's own service. An\nentry that carries an endpoint of its own is not probed: that URL is\ncaller-supplied and fetching it here would make this a way to have the\ngateway request an address of the caller's choosing.\n\nNot on ``verify_catalog_reader``, despite being a catalog read: that gate\nadmits any API key to the deployment-describing reads, and admitting a key\nhere would let any workspace credential dial the deployment's guardrails\nservice. This is a management read, so it takes the router's own gate.","operationId":"tool-settings-list_guardrail_profiles","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GuardrailCatalog"}}},"description":"Successful Response"}},"summary":"List Guardrail Profiles","tags":["tool-settings"]}}}}
```

## Set Sandbox Credential

> Store the key this deployment's hosted sandbox provider leases sandboxes with.\
> \
> Wins over the provider's environment variable (\`\`E2B\_API\_KEY\`\`), on this\
> worker at once and on every other within 30 seconds, so a rotated key needs\
> no redeploy. Refused for the \`\`protocol\`\` provider, which takes no key of\
> its own. Operator-gated.

```json
{"openapi":"3.1.0","info":{"title":"otari","version":"0.33.0"},"security":[{"ApiKeyAuth":[]},{"XApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Enter your API key here (sent as Otari-Key header).","in":"header","name":"Otari-Key","type":"apiKey"},"XApiKeyAuth":{"description":"Anthropic-native clients send credentials here (no Bearer prefix).","in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"SandboxCredentialRequest":{"description":"The key to lease hosted sandboxes with.","properties":{"api_key":{"minLength":1,"title":"Api Key","type":"string"}},"required":["api_key"],"title":"SandboxCredentialRequest","type":"object"},"SandboxCredentialPublic":{"description":"Where the key a hosted sandbox provider leases with comes from. Never the key itself.","properties":{"env_var":{"description":"The environment variable a deployment that stores no key is read from.","title":"Env Var","type":"string"},"last4":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The key's last four characters, to tell keys apart.","title":"Last4"},"source":{"anyOf":[{"enum":["stored","environment"],"type":"string"},{"type":"null"}],"description":"'stored' for a key set here, which wins; 'environment' for the provider's own environment variable; null when there is neither and code execution fails until one is set.","title":"Source"}},"required":["source","env_var"],"title":"SandboxCredentialPublic","type":"object"},"HTTPValidationError":{"properties":{"code":{"const":"invalid_request","description":"Stable error code, also sent as the Otari-Error-Code header.","title":"Code","type":"string"},"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}},"paths":{"/api/v1/tool-settings/sandbox/credential":{"put":{"description":"Store the key this deployment's hosted sandbox provider leases sandboxes with.\n\nWins over the provider's environment variable (``E2B_API_KEY``), on this\nworker at once and on every other within 30 seconds, so a rotated key needs\nno redeploy. Refused for the ``protocol`` provider, which takes no key of\nits own. Operator-gated.","operationId":"tool-settings-set_sandbox_credential","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxCredentialRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxCredentialPublic"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Set Sandbox Credential","tags":["tool-settings"]}}}}
```

## Clear Sandbox Credential

> Delete the stored sandbox key, so sandboxes are leased with the environment's key again.\
> \
> Clearing a key that was never stored is not an error. Operator-gated.

```json
{"openapi":"3.1.0","info":{"title":"otari","version":"0.33.0"},"security":[{"ApiKeyAuth":[]},{"XApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Enter your API key here (sent as Otari-Key header).","in":"header","name":"Otari-Key","type":"apiKey"},"XApiKeyAuth":{"description":"Anthropic-native clients send credentials here (no Bearer prefix).","in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"SandboxCredentialPublic":{"description":"Where the key a hosted sandbox provider leases with comes from. Never the key itself.","properties":{"env_var":{"description":"The environment variable a deployment that stores no key is read from.","title":"Env Var","type":"string"},"last4":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The key's last four characters, to tell keys apart.","title":"Last4"},"source":{"anyOf":[{"enum":["stored","environment"],"type":"string"},{"type":"null"}],"description":"'stored' for a key set here, which wins; 'environment' for the provider's own environment variable; null when there is neither and code execution fails until one is set.","title":"Source"}},"required":["source","env_var"],"title":"SandboxCredentialPublic","type":"object"}}},"paths":{"/api/v1/tool-settings/sandbox/credential":{"delete":{"description":"Delete the stored sandbox key, so sandboxes are leased with the environment's key again.\n\nClearing a key that was never stored is not an error. Operator-gated.","operationId":"tool-settings-clear_sandbox_credential","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxCredentialPublic"}}},"description":"Successful Response"}},"summary":"Clear Sandbox Credential","tags":["tool-settings"]}}}}
```

## Test Service

> Structurally validate a URL and probe it for reachability.\
> \
> Tests the URL in the request body (typically unsaved), so an operator can\
> verify before saving. The probe is a plain HTTP GET with a short timeout: any\
> HTTP response means the host is reachable; a connection/timeout/DNS error means\
> it is not. The operator is trusted (master key), so no SSRF deny-list applies;\
> only the structural check (http/https + host) runs first.

```json
{"openapi":"3.1.0","info":{"title":"otari","version":"0.33.0"},"security":[{"ApiKeyAuth":[]},{"XApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Enter your API key here (sent as Otari-Key header).","in":"header","name":"Otari-Key","type":"apiKey"},"XApiKeyAuth":{"description":"Anthropic-native clients send credentials here (no Bearer prefix).","in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"TestServiceRequest":{"description":"A (typically unsaved) URL to probe for reachability.","properties":{"url":{"title":"Url","type":"string"}},"required":["url"],"title":"TestServiceRequest","type":"object"},"TestServiceResponse":{"properties":{"ok":{"title":"Ok","type":"boolean"},"reason":{"title":"Reason","type":"string"}},"required":["ok","reason"],"title":"TestServiceResponse","type":"object"},"HTTPValidationError":{"properties":{"code":{"const":"invalid_request","description":"Stable error code, also sent as the Otari-Error-Code header.","title":"Code","type":"string"},"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}},"paths":{"/api/v1/tool-settings/{service}/test":{"post":{"description":"Structurally validate a URL and probe it for reachability.\n\nTests the URL in the request body (typically unsaved), so an operator can\nverify before saving. The probe is a plain HTTP GET with a short timeout: any\nHTTP response means the host is reachable; a connection/timeout/DNS error means\nit is not. The operator is trusted (master key), so no SSRF deny-list applies;\nonly the structural check (http/https + host) runs first.","operationId":"tool-settings-test_service","parameters":[{"in":"path","name":"service","required":true,"schema":{"title":"Service","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestServiceRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestServiceResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Test Service","tags":["tool-settings"]}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.otari.ai/otari/for-integrators/api-reference/tool-settings.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.