> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.runtype.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runtype.com/_mcp/server.

# Ensure agent (config-as-code converge)

POST https://api.runtype.com/v1/agents/ensure
Content-Type: application/json

Idempotently converge a repo-defined agent definition onto the platform. Identity is name + account scope. Hash-only probes skip the payload in the steady state (a miss is a normal 200 `definitionRequired` response, not an error); full requests create the agent or append a new version when the canonical content hash differs. Non-executing: never touches the execution pipeline. The response always carries the server-computed canonical hash. Set dryRun to plan without writing (CI drift gate), onConflict: "overwrite" to converge over dashboard/API edits, and deploy: \{ alias } to atomically save and activate the definition at a release alias (release: "publish" / "none" remain compatibility spellings of deploy live / save-only, and mixing the two is a 400). A non-live deploy is alias-scoped: it appends a candidate version and moves that one pointer, and never writes the agent row, its config hash, its capabilities, its draft pointer or its live pointer, so "unchanged" is decided against the hash stored on the alias rather than against the live row. onConflict, expectedRemoteHash and managed-by-code provenance describe live-row writes and therefore do not apply to a non-live deploy; remoteHash in the response is the hash the alias carried before. The one exception is an agent name that does not exist yet: the create is the live row (there is nothing to preview against), and live is still not aimed. Optional version.label / version.notes stamp provenance (a git SHA, a release tag) on the appended version row.

Reference: https://docs.runtype.com/api-reference/runtype-api/agents/ensure-agent-config-as-code-converge

## Authentication

- `Authorization` header (bearer token, required) — API key or Clerk session token

## Servers

- `https://api.runtype.com` (Production, default)
- `https://api.runtype-staging.com` (Staging)

## Request

### Body (application/json)

This endpoint expects an object.

- `name` (string, required)
- `capabilities` (list of AgentEnsureCapability, optional) — The complete set of capabilities (flow, sub-agent and saved-tool attachments) on this agent, in display order. Each entry names its source by name, so the declaration is portable across accounts. Capabilities on the agent but absent here are removed; omit the field to leave them untouched. When present, the capabilities are part of the content hash and of the version this converge snapshots. They are written to the agent itself, so they cannot accompany a non-live deploy.
- `contentHash` (string, optional)
- `definition` (V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinition, optional)
- `deploy` (AgentEnsureDeployTarget, optional) — Atomically save this definition and activate it at a release alias. Use \{ alias: "live" } to deploy to production, or any name matching ^\[a-z0-9]\[a-z0-9-]\{0,62}\$ for a preview pointer. A non-live alias appends a candidate version and moves that one pointer: it never writes the agent row, its config hash, its capabilities, its draft pointer or its live pointer, so onConflict and expectedRemoteHash describe writes it never performs and are rejected with a 400 alongside it. A release alias is organization-owned, so a non-live deploy on a personal-scope agent is a 400 with code alias\_requires\_organization. Mutually exclusive with release.
- `dryRun` (boolean, optional)
- `expectedRemoteHash` (string, optional)
- `onConflict` (enum, optional)
  - Allowed values: `error`, `overwrite`
- `release` (enum, optional) — Compatibility input, translated to a deploy: "publish" activates live, "none" saves without activating. Prefer deploy.
  - Allowed values: `none`, `publish`
- `skills` (list of AgentEnsureSkillBinding, optional) — The complete set of skills bound to this agent, in load order. Each entry names a skill by slug; `version` pins that skill versionNumber, and omitting it follows the skill's published version. Skills bound to the agent but absent here are unbound; omit the field to leave bindings untouched. Bindings are agent state, not alias state, so they take effect immediately and cannot accompany a non-live deploy.
- `version` (EnsureVersionMetadata, optional) — Provenance recorded on the version row this converge appends. Omit to keep the default "sdk-ensure" label and the server-generated notes.

## Response

### 200

Converge result: unchanged | created | updated | definitionRequired (hash miss — retry with the full definition) | plan (dryRun)

- `AgentEnsureResponse`
  - AgentEnsureResponse0
  - AgentEnsureResponse1
  - AgentEnsureResponse2

## Errors

### 400 Bad Request Error

Validation error, unsupported agent type, or code alias_requires_organization when a non-live deploy targets a personal-scope agent

- `error` (string, required)
- `code` (enum, optional) — A release alias is organization-owned, so a personal-scope agent cannot carry one.
  - Allowed values: `alias_requires_organization`

### 401 Unauthorized Error

Unauthorized

- `error` (string, required)
- `code` (string, optional) — Stable error code. `insufficient_scope` marks an API key that lacks a scope this request needs.
- `details` (list of ErrorDetailsItems, optional)
- `requiredScopes` (list of string, optional) — On `insufficient_scope`: every API key scope this request needs.

### 403 Forbidden Error

Insufficient permissions

- `error` (string, required)
- `code` (string, optional) — Stable error code. `insufficient_scope` marks an API key that lacks a scope this request needs.
- `details` (list of ErrorDetailsItems, optional)
- `requiredScopes` (list of string, optional) — On `insufficient_scope`: every API key scope this request needs.

### 409 Conflict Error

Conflict: external_modification (last write was not ensure; pass onConflict: "overwrite") or remote_changed (expectedRemoteHash guard)

- `code` (enum, required)
  - Allowed values: `external_modification`, `remote_changed`
- `error` (string, required)
- `currentHash` (string, optional, nullable)
- `lastModifiedSource` (string, optional)
- `modifiedAt` (string, optional, nullable)

### 422 Unprocessable Entity Error

Submitted contentHash does not match the server-recomputed canonical hash

- `code` (enum, required)
  - Allowed values: `content_hash_mismatch`
- `contentHash` (string, required) — The server-computed canonical hash of the submitted definition.
- `error` (string, required)

### 500 Internal Server Error

Internal server error, or code alias_activation_failed when a non-live activation could not be applied (nothing was written)

- `error` (string, required)
- `alias` (string, optional) — The release alias whose activation failed. No pointer was moved.
- `code` (enum, optional)
  - Allowed values: `alias_activation_failed`

## Types

### AgentEnsureCapability

- `toolName` (string, required) — The name the agent calls this capability by.
- `agent` (string, optional) — The name of another agent in this account scope, called as a sub-agent.
- `description` (string, optional)
- `enabled` (boolean, optional) — Defaults to true.
- `flow` (string, optional) — The name of a flow in this account scope.
- `parametersSchema` (map from string to any, optional) — JSON Schema for the capability's input. Omit to derive it from the flow's inputs or the tool's own schema.
- `tool` (string, optional) — The name of a saved tool in this account scope.

### V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinition

- `name` (string, required)
- `config` (V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfig, optional)
- `description` (string, optional)
- `icon` (string, optional)

### AgentEnsureDeployTarget

Atomically save this definition and activate it at a release alias. Use \{ alias: "live" } to deploy to production, or any name matching ^\[a-z0-9]\[a-z0-9-]\{0,62}\$ for a preview pointer. A non-live alias appends a candidate version and moves that one pointer: it never writes the agent row, its config hash, its capabilities, its draft pointer or its live pointer, so onConflict and expectedRemoteHash describe writes it never performs and are rejected with a 400 alongside it. A release alias is organization-owned, so a non-live deploy on a personal-scope agent is a 400 with code alias\_requires\_organization. Mutually exclusive with release.

- `alias` (string, required)
- `bindings` (map from string to string, optional) — The complete set of `{{secret:NAME}}` values executions resolve when they reach this agent through this pointer, ahead of the organization secret of the same name. One preview per pull request can aim its HTTP tools at that pull request environment while the version content stays byte-identical to what `live` runs. Whole-set replacement: a name you stop sending stops resolving, and an empty object clears them. Values are encrypted at rest and never returned; only their names appear on the deployment receipt.

### AgentEnsureSkillBinding

- `name` (string, required) — The skill slug.
- `enabled` (boolean, optional) — Defaults to true.
- `version` (integer, optional) — Pin this skill versionNumber. Omit to follow the skill's published version.

### EnsureVersionMetadata

Provenance recorded on the version row this converge appends. Omit to keep the default "sdk-ensure" label and the server-generated notes.

- `label` (string, optional) — Short provenance label recorded on the appended version row (e.g. a git SHA or release tag). Defaults to "sdk-ensure". An empty string is treated as omitted.
- `notes` (string, optional) — Free-form notes recorded on the appended version row, used verbatim. Defaults to the server-generated converge summary. An empty string is treated as omitted.

### AgentEnsureResponse0

- `agentId` (string, required)
- `contentHash` (string, required) — Server-computed canonical content hash. Clients should echo this hash in probes.
- `result` (enum, required)
  - Allowed values: `unchanged`, `created`, `updated`
- `versionId` (string, required, nullable) — The version snapshot backing this state (null if snapshotting failed).
- `_warnings` (list of string, optional) — Non-blocking advisories, e.g. SCHEDULE_AGENT_CONFIG_UNSUPPORTED when this converge (or, on a dry run, the planned one) changes what active schedules run into a version they cannot run.
- `capabilityChanges` (list of AgentEnsureCapabilityChange, optional) — Present when the request carried capabilities: one row per declared capability, then removals.
- `deployment` (AgentEnsureDeployment, optional) — Present when the converge carried release or deploy and the activation was applied.
- `remoteHash` (string, optional) — For a non-live deploy: the content hash the alias carried before this converge (absent when the alias is new).
- `skillBindings` (list of AgentEnsureSkillBindingChange, optional) — Present when the request carried skills: one row per declared binding, then unbinds.

### AgentEnsureResponse1

- `result` (enum, required)
  - Allowed values: `definitionRequired`

### AgentEnsureResponse2

- `changedKeys` (list of string, required)
- `changes` (enum, required)
  - Allowed values: `none`, `create`, `update`
- `contentHash` (string, required)
- `result` (enum, required)
  - Allowed values: `plan`
- `_warnings` (list of string, optional) — Non-blocking advisories, e.g. SCHEDULE_AGENT_CONFIG_UNSUPPORTED when this converge (or, on a dry run, the planned one) changes what active schedules run into a version they cannot run.
- `agentId` (string, optional)
- `capabilityChanges` (list of AgentEnsureCapabilityChange, optional) — Present when the request carried capabilities: one row per declared capability, then removals.
- `deployment` (AgentEnsureResponseOneOf2Deployment, optional) — Present when the dry run carried release or deploy: the pointer it would aim, and whether it would move.
- `remoteHash` (string, optional)
- `skillBindings` (list of AgentEnsureSkillBindingChange, optional) — Present when the request carried skills: one row per declared binding, then unbinds.

### ErrorDetailsItems

- `message` (string, required)
- `code` (string, optional) — Stable Runtype validation code (e.g. MISSING_REQUIRED_FIELD, INVALID_ENUM).
- `path` (string, optional) — Dotted JSON path to the offending field.
- `suggestion` (string, optional) — Actionable hint (allowed values, accepted range, …).

### V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfig

- `advisor` (V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigAdvisor, optional, nullable)
- `artifacts` (V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigArtifacts, optional)
- `busyMessageRouting` (V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigBusyMessageRouting, optional)
- `contextManagement` (V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigContextManagement, optional)
- `durability` (V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigDurability, optional)
- `errorHandling` (V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigErrorHandling, optional)
- `frequencyPenalty` (double, optional)
- `loggingPolicy` (enum, optional)
  - Allowed values: `default`, `on`, `off`
- `loopConfig` (V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigLoopConfig, optional)
- `maxTokens` (integer, optional)
- `memory` (V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigMemory, optional)
- `model` (string, optional)
- `piiRedaction` (enum, optional)
  - Allowed values: `default`, `off`, `redact`
- `presencePenalty` (double, optional)
- `reasoning` (V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigReasoning, optional)
- `sandbox` (V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigSandbox, optional)
- `seed` (integer, optional)
- `state` (V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigState, optional)
- `systemPrompt` (string, optional)
- `temperature` (double, optional)
- `temporal` (V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigTemporal, optional)
- `tenancyStrategy` (V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigTenancyStrategy, optional)
- `tools` (V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigTools, optional)
- `topK` (integer, optional)
- `topP` (double, optional)
- `voice` (V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigVoice, optional)

### AgentEnsureCapabilityChange

- `action` (enum, required) — What this converge did (on a dry run, would do) to the capability.
  - Allowed values: `add`, `update`, `remove`, `unchanged`
- `enabled` (boolean, required)
- `kind` (enum, required)
  - Allowed values: `flow`, `agent`, `tool`
- `source` (string, required, nullable) — The flow, agent or tool name the capability calls.
- `toolName` (string, required)

### AgentEnsureDeployment

Present when the converge carried release or deploy and the activation was applied.

- `alias` (string, required) — The release alias this converge aimed.
- `changed` (boolean, required) — Whether this converge moved the pointer (on a dry run, whether it would move it).
- `revision` (double, required, nullable) — Compare-and-swap revision of the alias, null when the alias does not exist yet.
- `versionId` (string, required, nullable) — The version the alias selects as of this response (null on a dry run against an alias that does not exist yet).
- `versionNumber` (double, required, nullable) — Version number of that version, when known.
- `bindingNames` (list of string, optional) — Per-alias secret binding names in force after this converge (on a dry run carrying deploy.bindings, the names it would leave in force). Never values.
- `bindingsChanged` (boolean, optional) — Present on a dry run carrying deploy.bindings: whether the binding names differ from the ones the alias carries now.
- `receiptId` (string, optional) — The deployment receipt this converge appended. Absent when the pointer did not move.

### AgentEnsureSkillBindingChange

- `action` (enum, required) — What this converge did (on a dry run, would do) to the binding.
  - Allowed values: `bind`, `update`, `unbind`, `unchanged`
- `enabled` (boolean, required)
- `name` (string, required) — The skill slug.
- `skillId` (string, required)
- `version` (double, required, nullable) — The pinned versionNumber; null follows the published version.

### AgentEnsureResponseOneOf2Deployment

Present when the dry run carried release or deploy: the pointer it would aim, and whether it would move.

- `alias` (string, required) — The release alias this converge aimed.
- `changed` (boolean, required) — Whether this converge moved the pointer (on a dry run, whether it would move it).
- `revision` (double, required, nullable) — Compare-and-swap revision of the alias, null when the alias does not exist yet.
- `versionId` (string, required, nullable) — The version the alias selects as of this response (null on a dry run against an alias that does not exist yet).
- `versionNumber` (double, required, nullable) — Version number of that version, when known.
- `bindingNames` (list of string, optional) — Per-alias secret binding names in force after this converge (on a dry run carrying deploy.bindings, the names it would leave in force). Never values.
- `bindingsChanged` (boolean, optional) — Present on a dry run carrying deploy.bindings: whether the binding names differ from the ones the alias carries now.
- `receiptId` (string, optional) — The deployment receipt this converge appended. Absent when the pointer did not move.

### V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigAdvisor

- `model` (string, required)
- `systemPrompt` (string, optional)

### V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigArtifacts

- `enabled` (boolean, required)
- `types` (list of enum, required)
  - Allowed values: `markdown`, `component`

### V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigBusyMessageRouting

- `classifierModel` (string, optional)
- `mode` (enum, optional)
  - Allowed values: `enforced`, `off`

### V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigContextManagement

- `compaction` (V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigContextManagementCompaction, optional)
- `toolResults` (V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigContextManagementToolResults, optional)

### V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigDurability

- `forced` (enum, optional)
  - Allowed values: `durable`, `in_process`
- `maxBudgetMs` (integer, optional, nullable)
- `watchLeaseMs` (integer, optional, nullable)

### V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigErrorHandling

- `onError` (enum, required)
  - Allowed values: `fail`, `continue`, `fallback`
- `fallbacks` (list of V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigErrorHandlingFallbacksItems, optional)
- `triggers` (list of V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigErrorHandlingTriggersItems, optional)

### V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigLoopConfig

- `enableReflection` (boolean, optional)
- `maxCost` (double, optional)
- `maxTurns` (integer, optional)
- `reflectionInterval` (integer, optional)
- `treatLengthCutoffAsFailure` (boolean, optional)

### V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigMemory

- `enabled` (boolean, required)
- `injectSummary` (boolean, optional)
- `pointerScope` (enum, optional)
  - Allowed values: `shared`, `alias`, `version`
- `profileTemplate` (string, optional)

### V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigReasoning

- boolean
- V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigReasoning1

### V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigSandbox

- `enabled` (boolean, required)
- `codingAgents` (list of enum, optional) — Coding agents the Sandbox can run as typed sessions. Non-empty adds the agent_session_* tools; empty or absent adds none.
  - Allowed values: `opencode`
- `instanceType` (enum, optional) — Only standard-4 is supported on the hosted Agent Sandbox path; other sizes cannot be enabled.
  - Allowed values: `standard-1`, `standard-2`, `standard-3`, `standard-4`
- `networkAccess` (V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigSandboxNetworkAccess, optional)
- `persistence` (enum, optional) — Supported: ephemeral or conversation. Named remains parseable for stored configs but cannot be enabled.
  - Allowed values: `ephemeral`, `conversation`, `named`
- `provider` (enum, optional) — Only runtype-sandbox is currently supported. Daytona is retained for stored-config parsing but rejected at authoring/execution.
  - Allowed values: `runtype-sandbox`, `daytona`
- `secretEnv` (map from string to string, optional)
- `setupCommands` (list of string, optional)
- `sleepAfter` (enum, optional)
  - Allowed values: `5m`, `15m`, `30m`, `1h`
- `ttl` (enum, optional)
  - Allowed values: `5m`, `1h`, `24h`, `unlimited`

### V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigState

- `initial` (map from string to any, optional)
- `mergeStrategy` (enum, optional, default: merge)
  - Allowed values: `replace`, `merge`
- `predictState` (list of V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigStatePredictStateItems, optional)
- `schema` (map from string to any, optional)

### V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigTemporal

- `elapsedThresholdSeconds` (integer, optional)
- `groundNow` (boolean, optional)
- `injectElapsed` (boolean, optional)
- `timezone` (string, optional)

### V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigTenancyStrategy

- `preset` (enum, required)
  - Allowed values: `internal`, `tenant-isolated`, `end-user-isolated`
- `assuranceFloor` (V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigTenancyStrategyAssuranceFloor, optional)

### V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigTools

- `approval` (V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigToolsApproval, optional)
- `codeModeConfig` (V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigToolsCodeModeConfig, optional)
- `intent` (enum, optional)
  - Allowed values: `mandatory`, `best-effort`
- `maxToolCalls` (integer, optional)
- `mcpServers` (list of V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigToolsMcpServersItems, optional)
- `perToolLimits` (map from string to V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigToolsPerToolLimits, optional)
- `runtimeTools` (list of V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigToolsRuntimeToolsItems, optional)
- `subagentConfig` (V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigToolsSubagentConfig, optional)
- `toolCallStrategy` (enum, optional)
  - Allowed values: `auto`, `required`, `none`
- `toolConfigs` (map from string to map from string to any, optional)
- `toolIds` (list of string, optional)
- `toolSearch` (V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigToolsToolSearch, optional)

### V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigVoice

- `directTools` (V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigVoiceDirectTools, optional)
- `disclosure` (boolean, optional)
- `elevenLabs` (V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigVoiceElevenLabs, optional)
- `enabled` (boolean, optional)
- `endpointing` (V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigVoiceEndpointing, optional)
- `greeting` (string, optional)
- `interruptionMode` (enum, optional)
  - Allowed values: `none`, `cancel`, `barge-in`
- `language` (string, optional)
- `provider` (string, optional)
- `speech` (V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigVoiceSpeech, optional)

### V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigContextManagementCompaction

- `enabled` (boolean, optional)
- `instructions` (string, optional)
- `model` (string, optional)
- `retainRecentTokens` (integer, optional)
- `strategy` (enum, optional)
  - Allowed values: `auto`, `provider_native`, `summary`
- `thresholdRatio` (double, optional)
- `thresholdTokens` (integer, optional)

### V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigContextManagementToolResults

- `pruneHotWindowTokens` (integer, optional)
- `pruneMode` (enum, optional)
  - Allowed values: `mask`, `off`
- `inlineThresholdChars` (integer, optional, deprecated) — Deprecated and ignored. Tool results are never spilled.

### V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigErrorHandlingFallbacksItems

- V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigErrorHandlingFallbacksItems0
- V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigErrorHandlingFallbacksItems1
- V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigErrorHandlingFallbacksItems2

### V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigErrorHandlingTriggersItems

- `type` (enum, required)
  - Allowed values: `error`, `empty-output`

### V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigReasoning1

- `enabled` (boolean, required)
- `budgetTokens` (integer, optional)
- `effort` (string, optional)
- `includeThoughts` (boolean, optional)
- `reasoningEffort` (enum, optional)
  - Allowed values: `minimal`, `low`, `medium`, `high`, `xhigh`, `max`
- `reasoningSummary` (enum, optional)
  - Allowed values: `auto`, `detailed`
- `thinkingBudget` (integer, optional)
- `thinkingLevel` (string, optional)

### V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigSandboxNetworkAccess

- enum
  - Allowed values: `none`, `essentials`, `open`
- V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigSandboxNetworkAccess1

### V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigStatePredictStateItems

- `stateKey` (string, required)
- `tool` (string, required)
- `toolArgument` (string, required)

### V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigTenancyStrategyAssuranceFloor

- `endUser` (enum, optional)
  - Allowed values: `asserted`, `verified`
- `tenant` (enum, optional)
  - Allowed values: `asserted`, `verified`

### V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigToolsApproval

- `require` (V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigToolsApprovalRequire, required)
- `approver` (enum, optional)
  - Allowed values: `owner`, `end-user`
- `choices` (V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigToolsApprovalChoices, optional)
- `requestReason` (boolean, optional)
- `timeout` (double, optional)

### V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigToolsCodeModeConfig

- `toolPool` (list of string, required)
- `description` (string, optional)
- `timeoutMs` (integer, optional)

### V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigToolsMcpServersItems

- `id` (string, required)
- `allowedTools` (list of string, optional)
- `auth` (V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigToolsMcpServersItemsAuth, optional)
- `enabled` (boolean, optional)
- `identityAudiences` (list of string, optional)
- `name` (string, optional)
- `target` (V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigToolsMcpServersItemsTarget, optional)
- `timeout` (double, optional)
- `transport` (enum, optional)
  - Allowed values: `streamable_http`, `rest`
- `url` (string, optional)

### V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigToolsPerToolLimits

- `maxCalls` (double, optional)
- `required` (boolean, optional)

### V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigToolsRuntimeToolsItems

- `config` (map from string to any, required)
- `description` (string, required)
- `name` (string, required)
- `parametersSchema` (map from string to any, required)
- `toolType` (enum, required)
  - Allowed values: `flow`, `custom`, `external`, `local`, `advisor`, `subagent`, `search`
- `hiddenParameterNames` (list of string, optional)
- `idempotent` (boolean, optional)

### V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigToolsSubagentConfig

- `toolPool` (list of string, required)
- `allowNesting` (boolean, optional)
- `defaultExecutionMode` (enum, optional)
  - Allowed values: `attached`, `detached`
- `defaultMaxTurns` (integer, optional)
- `defaultModel` (string, optional)
- `defaultNotify` (enum, optional)
  - Allowed values: `none`, `narrate`, `react`
- `defaultTimeoutMs` (integer, optional)
- `detachedMaxBudgetMs` (integer, optional)
- `detachedNoProgressBudgetMs` (integer, optional)
- `executionModes` (list of enum, optional)
  - Allowed values: `attached`, `detached`
- `maxSpawnsPerRun` (integer, optional)
- `maxTurnsLimit` (integer, optional)

### V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigToolsToolSearch

- `alwaysLoaded` (list of string, optional)
- `enabled` (boolean, optional)
- `threshold` (double, optional)

### V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigVoiceDirectTools

- `enabled` (boolean, optional)
- `model` (string, optional)

### V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigVoiceElevenLabs

- `modelId` (string, optional)
- `similarity` (double, optional)
- `stability` (double, optional)
- `voiceId` (string, optional)

### V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigVoiceEndpointing

- `strategy` (enum, required)
  - Allowed values: `provider_vad`, `server_vad`, `client_commit`, `manual`
- `silenceMs` (integer, optional)

### V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigVoiceSpeech

- `mode` (enum, required)
  - Allowed values: `pipeline`, `speech_to_speech`, `provider_managed`
- `synthesizer` (V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigVoiceSpeechSynthesizer, required)
- `transcriber` (V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigVoiceSpeechTranscriber, required)

### V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigErrorHandlingFallbacksItems0

- `type` (enum, required)
  - Allowed values: `retry`
- `delay` (integer, optional)

### V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigErrorHandlingFallbacksItems1

- `model` (string, required)
- `type` (enum, required)
  - Allowed values: `model`
- `delay` (integer, optional)
- `maxTokens` (integer, optional)
- `temperature` (double, optional)

### V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigErrorHandlingFallbacksItems2

- `message` (string, required)
- `type` (enum, required)
  - Allowed values: `message`
- `delay` (integer, optional)

### V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigSandboxNetworkAccess1

- `allow` (list of string, optional)
- `profile` (enum, optional)
  - Allowed values: `none`, `essentials`, `open`

### V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigToolsApprovalRequire

- list of string
- boolean

### V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigToolsApprovalChoices

- `alwaysAllow` (boolean, optional)
- `alwaysDeny` (boolean, optional)

### V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigToolsMcpServersItemsAuth

- `type` (enum, required)
  - Allowed values: `api_key`, `bearer`, `basic`, `custom_header`, `headers`, `none`
- `headerName` (string, optional)
- `headers` (map from string to string, optional)
- `password` (string, optional)
- `token` (string, optional)
- `username` (string, optional)

### V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigToolsMcpServersItemsTarget

- `deploymentId` (string, required)
- `kind` (enum, required)
  - Allowed values: `sandbox-deployment`
- `bearerSecretName` (string, optional)
- `path` (string, optional)

### V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigVoiceSpeechSynthesizer

- `provider` (string, required)
- `model` (string, optional)
- `settings` (V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigVoiceSpeechSynthesizerSettings, optional)
- `voiceId` (string, optional)

### V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigVoiceSpeechTranscriber

- `provider` (string, required)
- `model` (string, optional)

### V1AgentsEnsurePostRequestBodyContentApplicationJsonSchemaDefinitionConfigVoiceSpeechSynthesizerSettings

- `similarity` (double, optional)
- `stability` (double, optional)

## Examples

**Request**

```json
{
  "name": "string"
}
```

**Response**

```json
{
  "_warnings": [
    "string"
  ],
  "agentId": "string",
  "capabilityChanges": [
    {
      "action": "add",
      "enabled": true,
      "kind": "flow",
      "source": "string",
      "toolName": "string"
    }
  ],
  "contentHash": "string",
  "deployment": {
    "alias": "string",
    "bindingNames": [
      "string"
    ],
    "bindingsChanged": true,
    "changed": true,
    "receiptId": "string",
    "revision": 1.1,
    "versionId": "string",
    "versionNumber": 1.1
  },
  "remoteHash": "string",
  "result": "unchanged",
  "skillBindings": [
    {
      "action": "bind",
      "enabled": true,
      "name": "string",
      "skillId": "string",
      "version": 1.1
    }
  ],
  "versionId": "string"
}
```

**SDK Code**

```python
import requests

url = "https://api.runtype.com/v1/agents/ensure"

payload = { "name": "string" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.runtype.com/v1/agents/ensure';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"name":"string"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.runtype.com/v1/agents/ensure"

	payload := strings.NewReader("{\n  \"name\": \"string\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.runtype.com/v1/agents/ensure")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"string\"\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.runtype.com/v1/agents/ensure")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"string\"\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.runtype.com/v1/agents/ensure', [
  'body' => '{
  "name": "string"
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.runtype.com/v1/agents/ensure");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"name\": \"string\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = ["name": "string"] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.runtype.com/v1/agents/ensure")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```