agents: document Harness Runtime under /v2/harness-runtime

specification/DigitalOcean-public.v2.yaml

@@ -145,32 +145,33 @@ tags:
 
   - name: Harness Runtime
     description: |-
-      DigitalOcean Harness Runtime API under `/v2/agents`. An environment is a
-      reusable configuration that defines what an agent needs to do work; starting
-      a session from an environment provisions an isolated sandbox. Define an
-      environment with a YAML environment spec, or save it as an Environment Config
-      and create sessions from `{name, config_id}`.
+      DigitalOcean Harness Runtime API under `/v2/harness-runtime`. An
+      environment is a reusable configuration that defines what an agent needs
+      to do work; starting a session from an environment provisions an isolated
+      sandbox. Define an environment with a YAML environment spec, or save it as
+      an Environment Config and create sessions from `{name, config_id}`.
 
-      Environment Configs (`/v2/agents/configs`) are immutable team-scoped
+      Environment Configs (`/v2/harness-runtime/configs`) are immutable team-scoped
       configurations. Soft-delete releases the active name while keeping
       `config_id` resolvable for existing sessions; clone copies a sanitized
       environment under a new name (credentials are never copied).
 
       Checkpoints capture live sandbox machine state for fork and in-place
-      rollback. Templates (`/v2/agents/templates`) manage team custom sandbox
-      templates and their build history.
-
-      Triggers (`/v2/agents/triggers`) fire an agent run on a webhook delivery or
-      cron schedule, each firing recorded as an execution. The session event feed
-      (`GET /v2/agents/sessions/{session_id}/events`) is a Server-Sent Events
-      stream, and port-forward (`GET /v2/agents/sessions/{session_id}/port-forward/{port}`)
-      opens a WebSocket tunnel to a guest port.
-
-      `POST /v2/agents/sessions/{session_id}/cancel` stops the turn in flight.
-      `GET /v2/agents/image-messages` lists sandbox-image notices on the team's
-      sessions and checkpoints. `POST /v2/agents/auth/{provider}` starts the
+      rollback. Templates (`/v2/harness-runtime/templates`) manage team custom
+      sandbox templates and their build history.
+
+      Triggers (`/v2/harness-runtime/triggers`) fire an agent run on a webhook
+      delivery or cron schedule, each firing recorded as an execution. The
+      session event feed (`GET /v2/harness-runtime/sessions/{session_id}/events`)
+      is a Server-Sent Events stream, and port-forward
+      (`GET /v2/harness-runtime/sessions/{session_id}/port-forward/{port}`) opens
+      a WebSocket tunnel to a guest port.
+
+      `POST /v2/harness-runtime/sessions/{session_id}/cancel` stops the turn in flight.
+      `GET /v2/harness-runtime/image-messages` lists sandbox-image notices on the team's
+      sessions and checkpoints. `POST /v2/harness-runtime/auth/{provider}` starts the
       interactive provider login a session uses; `github` is the provider served
-      today. Connections for that login are under `/v2/agents/auth/{provider}/connections`.
+      today. Connections for that login are under `/v2/harness-runtime/auth/{provider}/connections`.
 
       Persistent workspaces (`/v2/agents/workspaces`) are in public preview and are
       described under Harness Runtime Workspaces [Public Preview].
@@ -1198,184 +1199,184 @@ paths:
     patch:
       $ref: "resources/addons/addons_update_plan.yml"
 
-  /v2/agents/auth/{provider}:
+  /v2/harness-runtime/auth/{provider}:
     post:
       $ref: "resources/agents/agents_start_provider_connect.yml"
-  /v2/agents/auth/{provider}/poll:
+  /v2/harness-runtime/auth/{provider}/poll:
     get:
       $ref: "resources/agents/agents_poll_provider_connect.yml"
-  /v2/agents/auth/{provider}/connections:
+  /v2/harness-runtime/auth/{provider}/connections:
     get:
       $ref: "resources/agents/agents_list_provider_connections.yml"
     post:
       $ref: "resources/agents/agents_create_provider_connection.yml"
-  /v2/agents/auth/{provider}/connections/{connection_id}:
+  /v2/harness-runtime/auth/{provider}/connections/{connection_id}:
     get:
       $ref: "resources/agents/agents_get_provider_connection.yml"
     delete:
       $ref: "resources/agents/agents_delete_provider_connection.yml"
-  /v2/agents/auth/{provider}/connections/{connection_id}/reconnect:
+  /v2/harness-runtime/auth/{provider}/connections/{connection_id}/reconnect:
     post:
       $ref: "resources/agents/agents_reconnect_provider_connection.yml"
-  /v2/agents/image-messages:
+  /v2/harness-runtime/image-messages:
     get:
       $ref: "resources/agents/agents_list_image_messages.yml"
-  /v2/agents/configs:
+  /v2/harness-runtime/configs:
     get:
       $ref: "resources/agents/agents_list_configs.yml"
     post:
       $ref: "resources/agents/agents_create_config.yml"
-  /v2/agents/configs/{config_id}:
+  /v2/harness-runtime/configs/{config_id}:
     get:
       $ref: "resources/agents/agents_get_config.yml"
     delete:
       $ref: "resources/agents/agents_delete_config.yml"
-  /v2/agents/configs/{config_id}/clone:
+  /v2/harness-runtime/configs/{config_id}/clone:
     post:
       $ref: "resources/agents/agents_create_config_clone.yml"
-  /v2/agents/configs/{config_id}/sessions:
+  /v2/harness-runtime/configs/{config_id}/sessions:
     get:
       $ref: "resources/agents/agents_list_config_sessions.yml"
-  /v2/agents/sessions:
+  /v2/harness-runtime/sessions:
     get:
       $ref: "resources/agents/agents_list_sessions.yml"
     post:
       $ref: "resources/agents/agents_create_session.yml"
-  /v2/agents/sessions/policy/validate:
+  /v2/harness-runtime/sessions/policy/validate:
     post:
       $ref: "resources/agents/agents_validate_session_policy.yml"
-  /v2/agents/sessions/sandbox/sizes:
+  /v2/harness-runtime/sessions/sandbox/sizes:
     get:
       $ref: "resources/agents/agents_list_session_sandbox_sizes.yml"
-  /v2/agents/sessions/{session_id}:
+  /v2/harness-runtime/sessions/{session_id}:
     delete:
       $ref: "resources/agents/agents_delete_session.yml"
     get:
       $ref: "resources/agents/agents_get_session.yml"
     patch:
       $ref: "resources/agents/agents_update_session.yml"
-  /v2/agents/sessions/{session_id}/checkpoints:
+  /v2/harness-runtime/sessions/{session_id}/checkpoints:
     get:
       $ref: "resources/agents/agents_list_session_checkpoints.yml"
     post:
       $ref: "resources/agents/agents_create_session_checkpoint.yml"
-  /v2/agents/sessions/{session_id}/checkpoints/{checkpoint_id}:
+  /v2/harness-runtime/sessions/{session_id}/checkpoints/{checkpoint_id}:
     get:
       $ref: "resources/agents/agents_get_session_checkpoint.yml"
     delete:
       $ref: "resources/agents/agents_delete_session_checkpoint.yml"
-  /v2/agents/sessions/{session_id}/checkpoints/{checkpoint_id}/image-messages:
+  /v2/harness-runtime/sessions/{session_id}/checkpoints/{checkpoint_id}/image-messages:
     get:
       $ref: "resources/agents/agents_get_checkpoint_image_messages.yml"
-  /v2/agents/sessions/{session_id}/checkpoints/{checkpoint_id}/rollback:
+  /v2/harness-runtime/sessions/{session_id}/checkpoints/{checkpoint_id}/rollback:
     post:
       $ref: "resources/agents/agents_revert_session_checkpoint.yml"
-  /v2/agents/sessions/{session_id}/fork:
+  /v2/harness-runtime/sessions/{session_id}/fork:
     post:
       $ref: "resources/agents/agents_create_session_fork.yml"
-  /v2/agents/sessions/{session_id}/hitl/{request_id}:
+  /v2/harness-runtime/sessions/{session_id}/hitl/{request_id}:
     post:
       $ref: "resources/agents/agents_post_session_hitl.yml"
-  /v2/agents/sessions/{session_id}/cancel:
+  /v2/harness-runtime/sessions/{session_id}/cancel:
     post:
       $ref: "resources/agents/agents_cancel_session_turn.yml"
-  /v2/agents/sessions/{session_id}/image-messages:
+  /v2/harness-runtime/sessions/{session_id}/image-messages:
     get:
       $ref: "resources/agents/agents_get_session_image_messages.yml"
-  /v2/agents/sessions/{session_id}/input:
+  /v2/harness-runtime/sessions/{session_id}/input:
     post:
       $ref: "resources/agents/agents_create_session_input.yml"
-  /v2/agents/sessions/{session_id}/pause:
+  /v2/harness-runtime/sessions/{session_id}/pause:
     post:
       $ref: "resources/agents/agents_post_session_pause.yml"
-  /v2/agents/sessions/{session_id}/resume:
+  /v2/harness-runtime/sessions/{session_id}/resume:
     post:
       $ref: "resources/agents/agents_post_session_resume.yml"
-  /v2/agents/sessions/{session_id}/sandbox/exec:
+  /v2/harness-runtime/sessions/{session_id}/sandbox/exec:
     post:
       $ref: "resources/agents/agents_post_session_sandbox_exec.yml"
-  /v2/agents/sessions/{session_id}/workspace/download:
+  /v2/harness-runtime/sessions/{session_id}/workspace/download:
     get:
       $ref: "resources/agents/agents_get_session_workspace_download.yml"
-  /v2/agents/sessions/{session_id}/workspace/transfers:
+  /v2/harness-runtime/sessions/{session_id}/workspace/transfers:
     post:
       $ref: "resources/agents/agents_create_session_workspace_transfer.yml"
-  /v2/agents/sessions/{session_id}/workspace/transfers/{transfer_id}:
+  /v2/harness-runtime/sessions/{session_id}/workspace/transfers/{transfer_id}:
     get:
       $ref: "resources/agents/agents_get_session_workspace_transfer.yml"
-  /v2/agents/sessions/{session_id}/workspace/transfers/{transfer_id}/cancel:
+  /v2/harness-runtime/sessions/{session_id}/workspace/transfers/{transfer_id}/cancel:
     post:
       $ref: "resources/agents/agents_cancel_session_workspace_transfer.yml"
-  /v2/agents/sessions/{session_id}/workspace/transfers/{transfer_id}/commit:
+  /v2/harness-runtime/sessions/{session_id}/workspace/transfers/{transfer_id}/commit:
     post:
       $ref: "resources/agents/agents_commit_session_workspace_transfer.yml"
-  /v2/agents/sessions/{session_id}/workspace/transfers/{transfer_id}/part-upload-urls:
+  /v2/harness-runtime/sessions/{session_id}/workspace/transfers/{transfer_id}/part-upload-urls:
     post:
       $ref: "resources/agents/agents_create_session_workspace_part_upload_urls.yml"
-  /v2/agents/sessions/{session_id}/workspace/upload:
+  /v2/harness-runtime/sessions/{session_id}/workspace/upload:
     post:
       $ref: "resources/agents/agents_create_session_workspace_upload.yml"
-  /v2/agents/sessions/{session_id}/events:
+  /v2/harness-runtime/sessions/{session_id}/events:
     get:
       $ref: "resources/agents/agents_stream_session_events.yml"
-  /v2/agents/sessions/{session_id}/port-forward/{port}:
+  /v2/harness-runtime/sessions/{session_id}/port-forward/{port}:
     get:
       $ref: "resources/agents/agents_port_forward_session.yml"
-  /v2/agents/sessions/{session_id}/ingress:
+  /v2/harness-runtime/sessions/{session_id}/ingress:
     get:
       $ref: "resources/agents/agents_get_session_ingress.yml"
-  /v2/agents/templates:
+  /v2/harness-runtime/templates:
     get:
       $ref: "resources/agents/agents_list_templates.yml"
     post:
       $ref: "resources/agents/agents_create_template.yml"
-  /v2/agents/templates/{template_id}:
+  /v2/harness-runtime/templates/{template_id}:
     get:
       $ref: "resources/agents/agents_get_template.yml"
     put:
       $ref: "resources/agents/agents_update_template.yml"
     delete:
       $ref: "resources/agents/agents_delete_template.yml"
-  /v2/agents/templates/{template_id}/builds:
+  /v2/harness-runtime/templates/{template_id}/builds:
     get:
       $ref: "resources/agents/agents_list_template_builds.yml"
-  /v2/agents/templates/{template_id}/builds/{build_id}:
+  /v2/harness-runtime/templates/{template_id}/builds/{build_id}:
     get:
       $ref: "resources/agents/agents_get_template_build.yml"
-  /v2/agents/triggers:
+  /v2/harness-runtime/triggers:
     get:
       $ref: "resources/agents/agents_list_triggers.yml"
     post:
       $ref: "resources/agents/agents_create_trigger.yml"
-  /v2/agents/triggers/by-session/{session_id}:
+  /v2/harness-runtime/triggers/by-session/{session_id}:
     get:
       $ref: "resources/agents/agents_get_trigger_by_session.yml"
-  /v2/agents/triggers/reusable-sessions:
+  /v2/harness-runtime/triggers/reusable-sessions:
     get:
       $ref: "resources/agents/agents_list_reusable_sessions.yml"
-  /v2/agents/triggers/{trigger_id}:
+  /v2/harness-runtime/triggers/{trigger_id}:
     get:
       $ref: "resources/agents/agents_get_trigger.yml"
     patch:
       $ref: "resources/agents/agents_update_trigger.yml"
     delete:
       $ref: "resources/agents/agents_delete_trigger.yml"
-  /v2/agents/triggers/{trigger_id}/executions:
+  /v2/harness-runtime/triggers/{trigger_id}/executions:
     get:
       $ref: "resources/agents/agents_list_trigger_executions.yml"
-  /v2/agents/triggers/{trigger_id}/executions/{execution_id}:
+  /v2/harness-runtime/triggers/{trigger_id}/executions/{execution_id}:
     get:
       $ref: "resources/agents/agents_get_trigger_execution.yml"
-  /v2/agents/triggers/{trigger_id}/executions/{execution_id}/cancel:
+  /v2/harness-runtime/triggers/{trigger_id}/executions/{execution_id}/cancel:
     post:
       $ref: "resources/agents/agents_cancel_trigger_execution.yml"
-  /v2/agents/triggers/{trigger_id}/rotate-secret:
+  /v2/harness-runtime/triggers/{trigger_id}/rotate-secret:
     post:
       $ref: "resources/agents/agents_rotate_trigger_secret.yml"
-  /v2/agents/triggers/{trigger_id}/webhook:
+  /v2/harness-runtime/triggers/{trigger_id}/webhook:
     post:
       $ref: "resources/agents/agents_receive_trigger_webhook.yml"
-  /v2/agents/webhook-providers:
+  /v2/harness-runtime/webhook-providers:
     get:
       $ref: "resources/agents/agents_list_webhook_providers.yml"
   /v2/agents/workspaces:

specification/resources/agents/agents_list_config_sessions.yml

@@ -1,7 +1,7 @@
 operationId: harness_list_config_sessions
 summary: List the sessions created from one Environment Config.
 description: Enumerates the caller's team sessions whose session was created from this durable Environment Config.
-  Keyset-paginated on an opaque cursor, newest first, same shape and status semantics as GET /v2/agents/sessions.
+  Keyset-paginated on an opaque cursor, newest first, same shape and status semantics as GET /v2/harness-runtime/sessions.
 tags:
 - Harness Runtime
 parameters:

specification/resources/agents/agents_port_forward_session.yml

@@ -5,7 +5,7 @@ description: |-
   guest `port`. Binary frames carry the opaque byte stream in both directions; the server closes with
   a descriptive WebSocket close code when the tunnel ends. This is the raw TCP tunnel; browser clients
   reaching the in-guest OpenHands Agent Server use the ingress URL
-  (`GET /v2/agents/sessions/{session_id}/ingress`), which has replaced this bridge for them.
+  (`GET /v2/harness-runtime/sessions/{session_id}/ingress`), which has replaced this bridge for them.
 
   WebSocket is not expressible in OpenAPI; this documents the GET that initiates the upgrade handshake
   (HTTP 101 Switching Protocols). The handler dials the guest before upgrading, so a PAUSED session is

specification/resources/agents/agents_receive_trigger_webhook.yml

@@ -16,6 +16,11 @@ description: |-
   On success (including a provider retry that dedupes to an existing firing) it returns 202 with the
   execution_id. A delivery to a paused trigger returns 202 with no body and queues nothing (deliberately
   not 409, so providers do not auto-disable the webhook after repeated non-2xx).
+
+  Both `/v2/agents/triggers/{trigger_id}/webhook` and
+  `/v2/harness-runtime/triggers/{trigger_id}/webhook` are accepted and keep working
+  indefinitely. Paste the `webhook_url` returned on the trigger into the external system
+  unchanged.
 tags:
 - Harness Runtime
 parameters:

specification/resources/agents/examples/curl/agents_cancel_session_turn.yml

@@ -1,3 +1,3 @@
 lang: bash
-source: "curl -X POST \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n  -d '{\"run_id\":\"run_example\"}' \\\n  \"https://api.digitalocean.com/v2/agents/sessions/{session_id}/cancel\""
+source: "curl -X POST \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n  -d '{\"run_id\":\"run_example\"}' \\\n  \"https://api.digitalocean.com/v2/harness-runtime/sessions/{session_id}/cancel\""
 label: cURL

specification/resources/agents/examples/curl/agents_cancel_session_workspace_transfer.yml

@@ -1,4 +1,4 @@
 lang: bash
 source: "curl -X POST \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\
-  \n  \"https://api.digitalocean.com/v2/agents/sessions/{session_id}/workspace/transfers/{transfer_id}/cancel\""
+  \n  \"https://api.digitalocean.com/v2/harness-runtime/sessions/{session_id}/workspace/transfers/{transfer_id}/cancel\""
 label: cURL

specification/resources/agents/examples/curl/agents_cancel_trigger_execution.yml

@@ -3,5 +3,5 @@ source: |-
   curl -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
-    "https://api.digitalocean.com/v2/agents/triggers/{trigger_id}/executions/{execution_id}/cancel"
+    "https://api.digitalocean.com/v2/harness-runtime/triggers/{trigger_id}/executions/{execution_id}/cancel"
 label: cURL

specification/resources/agents/examples/curl/agents_commit_session_workspace_transfer.yml

@@ -1,4 +1,4 @@
 lang: bash
 source: "curl -X POST \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\
-  \n  \"https://api.digitalocean.com/v2/agents/sessions/{session_id}/workspace/transfers/{transfer_id}/commit\""
+  \n  \"https://api.digitalocean.com/v2/harness-runtime/sessions/{session_id}/workspace/transfers/{transfer_id}/commit\""
 label: cURL

specification/resources/agents/examples/curl/agents_create_config.yml

@@ -1,5 +1,5 @@
 lang: bash
 source: "curl -X POST \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\
   \n  -d '{\"name\":\"support-agent\",\"manifest_yaml\":\"apiVersion: agents.digitalocean.com/v1alpha1\\nkind:\
-  \ Agent\\nspec:\\n  runtime:\\n    adapter: opencode\\n\"}' \\\n  \"https://api.digitalocean.com/v2/agents/configs\""
+  \ Agent\\nspec:\\n  runtime:\\n    adapter: opencode\\n\"}' \\\n  \"https://api.digitalocean.com/v2/harness-runtime/configs\""
 label: cURL

specification/resources/agents/examples/curl/agents_create_config_clone.yml

@@ -1,3 +1,3 @@
 "lang": "bash"
-"source": "curl -X POST \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n  -d '{\"name\":\"support-agent-v2\"}' \\\n  \"https://api.digitalocean.com/v2/agents/configs/{config_id}/clone\""
+"source": "curl -X POST \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n  -d '{\"name\":\"support-agent-v2\"}' \\\n  \"https://api.digitalocean.com/v2/harness-runtime/configs/{config_id}/clone\""
 "label": "cURL"

specification/resources/agents/examples/curl/agents_create_provider_connection.yml

@@ -1,3 +1,3 @@
 lang: bash
-source: "curl -X POST \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n  -d '{\"user_id\":\"octocat\"}' \\\n  \"https://api.digitalocean.com/v2/agents/auth/{provider}/connections\""
+source: "curl -X POST \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n  -d '{\"user_id\":\"octocat\"}' \\\n  \"https://api.digitalocean.com/v2/harness-runtime/auth/{provider}/connections\""
 label: cURL

specification/resources/agents/examples/curl/agents_create_session.yml

@@ -4,5 +4,5 @@ source: |-
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
     -d '{"name":"demo-agent","config_id":"019fb39c-14d9-7080-933e-b9b90e25acda"}' \
-    "https://api.digitalocean.com/v2/agents/sessions"
+    "https://api.digitalocean.com/v2/harness-runtime/sessions"
 label: cURL

specification/resources/agents/examples/curl/agents_create_session_checkpoint.yml

@@ -1,3 +1,3 @@
 "lang": "bash"
-"source": "curl -X POST \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n  -d '{\"label\":\"before-refactor\"}' \\\n  \"https://api.digitalocean.com/v2/agents/sessions/{session_id}/checkpoints\""
+"source": "curl -X POST \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n  -d '{\"label\":\"before-refactor\"}' \\\n  \"https://api.digitalocean.com/v2/harness-runtime/sessions/{session_id}/checkpoints\""
 "label": "cURL"

specification/resources/agents/examples/curl/agents_create_session_fork.yml

@@ -1,3 +1,3 @@
 "lang": "bash"
-"source": "curl -X POST \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n  -d '{\"count\":1}' \\\n  \"https://api.digitalocean.com/v2/agents/sessions/{session_id}/fork\""
+"source": "curl -X POST \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n  -d '{\"count\":1}' \\\n  \"https://api.digitalocean.com/v2/harness-runtime/sessions/{session_id}/fork\""
 "label": "cURL"