---
title: "Register a new harness version [write]"
method: POST
path: "/harnesses/{id}/versions"
tags: ["harnesses"]
---

# Register a new harness version \[write\]

`POST /harnesses/{id}/versions`

## Request

- Base URL: `https://api.agentsky.dev/v1`
- URL: `https://api.agentsky.dev/v1/harnesses/{id}/versions`
- Auth: HTTP bearer

Registers the version string and triggers an E2B template build. Poll the version's status until it reaches ready, then promote with POST /harnesses/{id}/versions/{v}/current. If profile is omitted, the parent harness's profile is used. Returns 404 when the WORKSPACE_HARNESSES feature switch is off for this workspace. Returns 503 not_migrated when the backing tables are not yet present.

## Path parameters

- `id` string, required

## Request body

- CreateHarnessVersion
  - `version` string, required
  - `profile` object
    - `id` string, required
    - `name` string, required
    - `version` string, required
    - `distribution` union
      - object
      - object
        - `oci` object, required
          - `image` string, required
    - `auth_command` string[]
    - `bundled_mcp_servers` object[]
    - `configuration_files` object[]
    - `credential_args` object
    - `graceful_exit_timeout_seconds` number
    - `home_directories` string[]
    - `managed_model_id_template` string
    - `native_provider_setup` object
    - `pipeline` string
    - `prerequisites` object
    - `request_timeout_seconds` number
    - `requirements` string[]
    - `session_close_before_exit` boolean
    - `session_config_options` object
    - `session_load_supported` boolean
    - `session_parameters` object
    - `subscription_files` boolean
    - `docker_target` string
    - `tools` object[]
      - `id` string, required
      - `kind` string, required
      - `title` string
      - `requires` object
    - `features` string[]
    - `placement` 'in_sandbox' | 'remote'

## Response `201`

Created

- object
  - `version` HarnessVersion, required
    - `id` string, required: hrnv_… — internal version row id
    - `harness_id` string, required: hrn_… — the parent harness
    - `version` string, required: Version string, e.g. v1-4096m
    - `status` 'pending' | 'building' | 'ready' | 'current' | 'revoked', required: pending: registered, build not started. building: E2B template build in progress. ready: build succeeded; can be promoted. current: the version agents are created against; at most one per harness. revoked: explicitly withdrawn; cannot be promoted or used for new sessions.
    - `profile` HarnessProfile, required: The runtime description of a workspace harness: the distribution spec (npx, uvx or binary), optional auth command, bundled MCP servers, tools, features and other catalog fields the installer reads when it builds the template image.
      - `id` string, required
      - `name` string, required
      - `version` string, required
      - `distribution` union
        - object
        - object
          - `oci` object, required
            - `image` string, required
      - `auth_command` string[]
      - `bundled_mcp_servers` object[]
      - `configuration_files` object[]
      - `credential_args` object
      - `graceful_exit_timeout_seconds` number
      - `home_directories` string[]
      - `managed_model_id_template` string
      - `native_provider_setup` object
      - `pipeline` string
      - `prerequisites` object
      - `request_timeout_seconds` number
      - `requirements` string[]
      - `session_close_before_exit` boolean
      - `session_config_options` object
      - `session_load_supported` boolean
      - `session_parameters` object
      - `subscription_files` boolean
      - `docker_target` string
      - `tools` object[]
        - `id` string, required
        - `kind` string, required
        - `title` string
        - `requires` object
      - `features` string[]
      - `placement` 'in_sandbox' | 'remote'
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required

## Other responses

- `default`: Error — { error: { code, message } }

## Changes

- **2026-11-02** `e5e8f0229a99`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/agentsky/apis/agentsky-developer-api/changes/harnesses/:id/versions/post.md)

---

[API](https://skmtc.dev/agentsky/apis/agentsky-developer-api.md) - [All operations](https://skmtc.dev/agentsky/apis/agentsky-developer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/agentsky/apis/agentsky-developer-api/revisions/8280a065ef6a?raw)