API referenceEndpointsAgents
agents.promote
RPC agents.promote · Scope control
AuthorizationBearer <token>
A Plane API key, pl_<env>_…. The key is the environment: everything it reads and writes is scoped to the environment it was minted in, and the two tenancy headers are ignored for one.
In: header
Header Parameters
x-plane-environment?string
The environment slug this request is about. Honoured only for a session cookie; ignored for an API key, whose environment is its identity.
x-plane-organization?string
The organization slug or id this request is about, resolved before the environment. Honoured only for a session cookie.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/agents/promote" \ -H "Content-Type: application/json" \ -d '{ "agentId": "string", "to": "string" }'{ "agentId": "string", "version": 1, "definition": { "name": "string", "description": "string", "model": { "provider": "string", "model": "string", "reasoning": "none", "fallback": { "models": [ { "provider": "string", "model": "string", "reasoning": "none" } ], "on": [ "unavailable" ], "timeoutMs": 1 }, "caching": { "mode": "auto", "ttl": "5m", "keepWarm": { "enabled": true, "idleAfterMinutes": 1, "maxConcurrentPrefixes": 1, "spendCapUsdPerDay": 0 } } }, "system": "string", "tools": [ { "type": "builtin", "name": "current_time" } ], "toolLoading": { "mode": "eager", "autoThreshold": 1 }, "policies": { "toolCalls": { "hook": { "connection": "string" }, "default": "allow", "byTool": { "property1": "allow", "property2": "allow" }, "onError": "allow", "onTimeout": "allow", "timeoutMs": 100 }, "decisions": { "expiresInSeconds": 30, "onExpire": "deny" } }, "limits": { "maxTurns": 1, "maxInputTokensPerSession": 1 }, "compaction": { "mode": "auto", "thresholdPercent": 0, "contextTokens": 1, "reserveOutputTokens": 0, "prompt": "string", "model": { "provider": "string", "model": "string", "reasoning": "none" }, "keepRecentMessages": 0, "preserve": [ "tool_results" ], "dropToolResultsAfterTokens": 1 }, "overrides": { "model": true, "reasoning": true, "system": "none", "compaction": true, "sandbox": true }, "subagents": [ { "kind": "agent", "name": "string", "description": "string", "agent": "string", "version": 1 } ], "subagentPolicy": { "selfDelegation": true, "maxDepth": 0, "maxConcurrent": 1, "maxTotalPerSession": 1, "childInputTokenBudget": 1 }, "sandbox": { "provider": "modal", "connectionName": "string", "image": { "base": "string", "steps": [ "string" ], "secrets": [ "string" ] }, "resources": { "cpu": 0, "memoryMb": 128 }, "network": { "egress": { "mode": "unrestricted" } }, "idleTimeoutMs": 1000, "preview": { "enabled": true, "auth": "signed-url" }, "scope": "tree", "tools": { "preset": "read-only", "allow": [ "string" ], "deny": [ "string" ] }, "serializeTools": true, "lifecycle": { "idleAfterMs": 1000, "onIdle": "release", "snapshotEveryMs": 1000, "keepSnapshots": 0, "resume": "snapshot", "maxSnapshotAgeMs": 1000 } }, "identity": { "required": true, "switchable": true, "scopesAllowed": [ "string" ] } }, "createdAt": "string", "image": { "status": "baking", "ref": "string", "specHash": "string", "bakedAt": "string", "error": "string" }, "promotedFrom": { "environmentId": "string", "agentId": "string", "version": 1 }}