Pull agent definition (config-as-code)

GET

/v1/agents/pull

GET

/v1/agents/pull

curl -G https://api.runtype.com/v1/agents/pull \
     -H "Authorization: <apiKey>" \
     -d name=name

{
  "agentId": "string",
  "capabilities": [
    {
      "toolName": "string",
      "agent": "string",
      "description": "string",
      "enabled": true,
      "flow": "string",
      "parametersSchema": {},
      "tool": "string"
    }
  ],
  "contentHash": "string",
  "definition": {
    "name": "string",
    "config": {
      "advisor": {
        "model": "string",
        "systemPrompt": "string"
      },
      "artifacts": {
        "enabled": true,
        "types": [
          "markdown"
        ]
      },
      "busyMessageRouting": {
        "classifierModel": "string",
        "mode": "enforced"
      },
      "contextManagement": {
        "compaction": {
          "enabled": true,
          "instructions": "string",
          "model": "string",
          "retainRecentTokens": 1,
          "strategy": "auto",
          "thresholdRatio": 0.64,
          "thresholdTokens": 1
        },
        "toolResults": {
          "pruneHotWindowTokens": 1,
          "pruneMode": "mask",
          "inlineThresholdChars": 1
        }
      },
      "durability": {
        "forced": "durable",
        "maxBudgetMs": 1,
        "watchLeaseMs": 1
      },
      "errorHandling": {
        "onError": "fail",
        "fallbacks": [
          {
            "delay": 1,
            "type": "retry"
          }
        ],
        "triggers": [
          {
            "type": "error"
          }
        ]
      },
      "frequencyPenalty": 1.1,
      "loggingPolicy": "default",
      "loopConfig": {
        "enableReflection": true,
        "maxCost": 1.1,
        "maxTurns": 1,
        "reflectionInterval": 1,
        "treatLengthCutoffAsFailure": true
      },
      "maxTokens": 1,
      "memory": {
        "enabled": true,
        "injectSummary": true,
        "pointerScope": "shared",
        "profileTemplate": "string"
      },
      "model": "string",
      "piiRedaction": "default",
      "presencePenalty": 1.1,
      "reasoning": true,
      "sandbox": {
        "enabled": true,
        "codingAgents": [
          "opencode"
        ],
        "instanceType": "standard-1",
        "networkAccess": "none",
        "persistence": "ephemeral",
        "provider": "runtype-sandbox",
        "secretEnv": {},
        "setupCommands": [
          "string"
        ],
        "sleepAfter": "5m",
        "ttl": "5m"
      },
      "seed": 1,
      "state": {
        "initial": {},
        "mergeStrategy": "merge",
        "predictState": [
          {
            "stateKey": "string",
            "tool": "string",
            "toolArgument": "string"
          }
        ],
        "schema": {}
      },
      "systemPrompt": "string",
      "temperature": 1.1,
      "temporal": {
        "elapsedThresholdSeconds": 1,
        "groundNow": true,
        "injectElapsed": true,
        "timezone": "string"
      },
      "tenancyStrategy": {
        "preset": "internal",
        "assuranceFloor": {
          "endUser": "asserted",
          "tenant": "asserted"
        }
      },
      "tools": {
        "approval": {
          "require": [
            "string"
          ],
          "approver": "owner",
          "choices": {
            "alwaysAllow": true,
            "alwaysDeny": true
          },
          "requestReason": true,
          "timeout": 1.1
        },
        "codeModeConfig": {
          "toolPool": [
            "string"
          ],
          "description": "string",
          "timeoutMs": 1
        },
        "maxToolCalls": 1,
        "mcpServers": [
          {
            "id": "string",
            "url": "string",
            "allowedTools": [
              "string"
            ],
            "auth": {
              "type": "api_key",
              "headerName": "string",
              "headers": {},
              "password": "string",
              "token": "string",
              "username": "string"
            },
            "enabled": true,
            "identityAudiences": [
              "string"
            ],
            "name": "string",
            "timeout": 1.1,
            "transport": "streamable_http"
          }
        ],
        "perToolLimits": {},
        "runtimeTools": [
          {
            "config": {},
            "description": "string",
            "name": "string",
            "parametersSchema": {},
            "toolType": "flow",
            "hiddenParameterNames": [
              "string"
            ],
            "idempotent": true
          }
        ],
        "subagentConfig": {
          "toolPool": [
            "string"
          ],
          "allowNesting": true,
          "defaultExecutionMode": "attached",
          "defaultMaxTurns": 1,
          "defaultModel": "string",
          "defaultNotify": "none",
          "defaultTimeoutMs": 1,
          "detachedMaxBudgetMs": 1,
          "detachedNoProgressBudgetMs": 1,
          "executionModes": [
            "attached"
          ],
          "maxSpawnsPerRun": 1,
          "maxTurnsLimit": 1
        },
        "toolCallStrategy": "auto",
        "toolConfigs": {},
        "toolIds": [
          "string"
        ],
        "toolSearch": {
          "alwaysLoaded": [
            "string"
          ],
          "enabled": true,
          "threshold": 1.1
        }
      },
      "topK": 1,
      "topP": 0.5,
      "voice": {
        "directTools": {
          "enabled": true,
          "model": "string"
        },
        "disclosure": true,
        "elevenLabs": {
          "modelId": "string",
          "similarity": 0.5,
          "stability": 0.5,
          "voiceId": "string"
        },
        "enabled": true,
        "endpointing": {
          "strategy": "provider_vad",
          "silenceMs": 1
        },
        "greeting": "string",
        "interruptionMode": "none",
        "language": "string",
        "provider": "string",
        "speech": {
          "mode": "pipeline",
          "synthesizer": {
            "provider": "string",
            "model": "string",
            "settings": {
              "similarity": 0.5,
              "stability": 0.5
            },
            "voiceId": "string"
          },
          "transcriber": {
            "provider": "string",
            "model": "string"
          }
        }
      }
    },
    "description": "string",
    "icon": "string"
  },
  "lastModifiedSource": "string",
  "skills": [
    {
      "name": "string",
      "enabled": true,
      "version": 1
    }
  ],
  "updatedAt": "string",
  "versionId": "string",
  "warnings": [
    "string"
  ]
}

Return the canonical config-as-code definition and provenance for an agent by name — the absorb-drift direction of the ensure protocol. The contentHash is recomputed from the live agent state, so it is accurate even immediately after a dashboard edit.

Authentication

AuthorizationBearer

API key or Clerk session token

Query parameters

namestringRequired>=1 character

Response

Canonical definition + provenance

agentIdstring

capabilitieslist of objects

The agent's capabilities in display order, in the shape ensure's capabilities accepts. parametersSchema appears only when it differs from the one ensure would derive.

contentHashstring

definitionobject

lastModifiedSourcestring or null

skillslist of objects

The agent's skill bindings in load order, in the shape ensure's skills accepts.

updatedAtstring or null

versionIdstring or null

warningslist of stringsOptional

Present only when a raw tool_… reference could not be emitted as a portable tool:<name> (the tool was deleted, or its name is shadowed by an older same-named tool). Those references are left as raw ids, which the ensure surface rejects; each warning explains how to fix it.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

500

Internal Server Error