Ensure skill (config-as-code converge)

POST

/v1/skills/ensure

Idempotently converge a repo-defined skill (SKILL.md manifest) 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 skill or append a new version when the canonical content hash differs. The response always carries the server-computed canonical hash + the version id. Set dryRun to plan without writing (CI drift gate), onConflict: “overwrite” to converge over dashboard/API edits, and release: “publish” to publish the converged version. Admin/control plane only — no review queue.

Idempotently converge a repo-defined skill (SKILL.md manifest) 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 skill or append a new version when the canonical content hash differs. The response always carries the server-computed canonical hash + the version id. Set dryRun to plan without writing (CI drift gate), onConflict: "overwrite" to converge over dashboard/API edits, and release: "publish" to publish the converged version. Admin/control plane only — no review queue.

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/skills/ensure \
>	-H "Authorization: <apiKey>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"name": "weather-forecast-skill"
>	}'

1	{
2	"contentHash": "a3f5c2d4e6b7890f1234567890abcdef1234567890abcdef1234567890abcdef",
3	"result": "unchanged",
4	"skillId": "skill_9876543210abcdef",
5	"versionId": "v1.3.0"
6	}