Ensure agent (config-as-code converge)

POST

/v1/agents/ensure

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 release: “publish” to also re-aim the published-version pointer.

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 release: "publish" to also re-aim the published-version pointer.

Authentication

AuthorizationBearer

API key or Clerk session token

Request

This endpoint expects an object.

namestringRequired>=1 character

contentHashstringOptionalformat: "^[0-9a-f]{64}$"

definitionobjectOptional

dryRunbooleanOptional

expectedRemoteHashstringOptionalformat: "^[0-9a-f]{64}$"

onConflictenumOptional

Allowed values:

releaseenumOptional

Allowed values:

Response

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

object

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

409

Conflict Error

422

Unprocessable Entity Error

500

Internal Server Error

$	curl -X POST https://api.runtype.com/v1/agents/ensure \
>	-H "Authorization: <apiKey>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"name": "data-sync-agent"
>	}'

1	{
2	"agentId": "agent_12345abcde",
3	"contentHash": "a3f5c2d4e6b7890f1234567890abcdef1234567890abcdef1234567890abcdef",
4	"result": "unchanged",
5	"versionId": "v1.0.3"
6	}