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 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.

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.

Authentication

AuthorizationBearer

API key or Clerk session token

Request

This endpoint expects an object.

namestringRequired>=1 character

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

definitionobjectOptional

deployobjectOptional

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.

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.

dryRunbooleanOptional

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

onConflictenumOptional

Allowed values:

releaseenumOptional

Compatibility input, translated to a deploy: “publish” activates live, “none” saves without activating. Prefer deploy.

Allowed values:

versionobjectOptional

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

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

429

Too Many Requests 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": "string"
>	}'

1	{
2	"agentId": "string",
3	"contentHash": "string",
4	"deployment": {
5	"alias": "string",
6	"changed": true,
7	"receiptId": "string",
8	"revision": 1.1,
9	"versionId": "string",
10	"versionNumber": 1.1
11	},
12	"remoteHash": "string",
13	"result": "unchanged",
14	"versionId": "string"
15	}