Add Hosted Agents /v2/agents OpenAPI (full harness surface)

specification/DigitalOcean-public.v2.yaml

@@ -84,6 +84,23 @@ tags:
     description: |-
       The API lets you build GPU-powered AI agents with pre-built or custom foundation models, function and agent routes, and RAG pipelines with knowledge bases.
 
+  - 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}`.
+
+      Environment Configs (`/v2/agents/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.
+
   - name: Apps
     description: |-
       App Platform is a Platform-as-a-Service (PaaS) offering from DigitalOcean that allows
@@ -748,6 +765,7 @@ x-tagGroups:
       - Floating IP Actions
       - Floating IPs
       - Functions
+      - Harness Runtime
       - Image Actions
       - Images
       - Insights
@@ -1001,6 +1019,111 @@ paths:
     patch:
       $ref: "resources/addons/addons_update_plan.yml"
 
+  /v2/agents/configs:
+    get:
+      $ref: "resources/agents/agents_list_configs.yml"
+    post:
+      $ref: "resources/agents/agents_create_config.yml"
+  /v2/agents/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:
+    post:
+      $ref: "resources/agents/agents_create_config_clone.yml"
+  /v2/agents/configs/{config_id}/sessions:
+    get:
+      $ref: "resources/agents/agents_list_config_sessions.yml"
+  /v2/agents/sessions:
+    get:
+      $ref: "resources/agents/agents_list_sessions.yml"
+    post:
+      $ref: "resources/agents/agents_create_session.yml"
+  /v2/agents/sessions/policy/validate:
+    post:
+      $ref: "resources/agents/agents_validate_session_policy.yml"
+  /v2/agents/sessions/sandbox/sizes:
+    get:
+      $ref: "resources/agents/agents_list_session_sandbox_sizes.yml"
+  /v2/agents/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:
+    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}:
+    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}/rollback:
+    post:
+      $ref: "resources/agents/agents_revert_session_checkpoint.yml"
+  /v2/agents/sessions/{session_id}/fork:
+    post:
+      $ref: "resources/agents/agents_create_session_fork.yml"
+  /v2/agents/sessions/{session_id}/hitl/{request_id}:
+    post:
+      $ref: "resources/agents/agents_post_session_hitl.yml"
+  /v2/agents/sessions/{session_id}/input:
+    post:
+      $ref: "resources/agents/agents_create_session_input.yml"
+  /v2/agents/sessions/{session_id}/pause:
+    post:
+      $ref: "resources/agents/agents_post_session_pause.yml"
+  /v2/agents/sessions/{session_id}/resume:
+    post:
+      $ref: "resources/agents/agents_post_session_resume.yml"
+  /v2/agents/sessions/{session_id}/sandbox/exec:
+    post:
+      $ref: "resources/agents/agents_post_session_sandbox_exec.yml"
+  /v2/agents/sessions/{session_id}/workspace/download:
+    get:
+      $ref: "resources/agents/agents_get_session_workspace_download.yml"
+  /v2/agents/sessions/{session_id}/workspace/transfers:
+    post:
+      $ref: "resources/agents/agents_create_session_workspace_transfer.yml"
+  /v2/agents/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:
+    post:
+      $ref: "resources/agents/agents_cancel_session_workspace_transfer.yml"
+  /v2/agents/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:
+    post:
+      $ref: "resources/agents/agents_create_session_workspace_part_upload_urls.yml"
+  /v2/agents/sessions/{session_id}/workspace/upload:
+    post:
+      $ref: "resources/agents/agents_create_session_workspace_upload.yml"
+  /v2/agents/templates:
+    get:
+      $ref: "resources/agents/agents_list_templates.yml"
+    post:
+      $ref: "resources/agents/agents_create_template.yml"
+  /v2/agents/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:
+    get:
+      $ref: "resources/agents/agents_list_template_builds.yml"
+  /v2/agents/templates/{template_id}/builds/{build_id}:
+    get:
+      $ref: "resources/agents/agents_get_template_build.yml"
+
   /v2/apps:
     get:
       $ref: "resources/apps/apps_list.yml"

specification/resources/agents/agents_cancel_session_workspace_transfer.yml

@@ -0,0 +1,77 @@
+operationId: harness_cancel_session_workspace_transfer
+summary: Cancel a staged workspace transfer.
+description: 'Aborts an in-flight transfer. Idempotent: cancelling an already-terminal transfer returns
+  `aborted: false` with the current status. The request body is optional.'
+tags:
+- Harness Runtime
+parameters:
+- in: path
+  name: session_id
+  required: true
+  description: The session UUID.
+  schema:
+    type: string
+    example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
+  example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
+- in: path
+  name: transfer_id
+  required: true
+  description: The workspace transfer identifier.
+  schema:
+    type: string
+    example: tr_example
+  example: tr_example
+requestBody:
+  required: false
+  content:
+    application/json:
+      schema:
+        type: object
+        properties:
+          reason:
+            type: string
+            description: Optional caller-visible audit/debug context.
+            example: example
+responses:
+  '200':
+    description: Cancel processed.
+    headers: &id001
+      ratelimit-limit:
+        $ref: ../../shared/headers.yml#/ratelimit-limit
+      ratelimit-remaining:
+        $ref: ../../shared/headers.yml#/ratelimit-remaining
+      ratelimit-reset:
+        $ref: ../../shared/headers.yml#/ratelimit-reset
+    content:
+      application/json:
+        schema:
+          $ref: models/definitions.yml#/workspace_transfer_cancelled
+  '401':
+    $ref: ../../shared/responses/unauthorized.yml
+  '404':
+    $ref: ../../shared/responses/not_found.yml
+  '501':
+    description: Cancel is not supported by the active sandbox driver.
+    headers: *id001
+    content:
+      application/json:
+        schema:
+          $ref: models/definitions.yml#/error
+  '423':
+    description: This session is unavailable; contact support.
+    headers: *id001
+    content:
+      application/json:
+        schema:
+          $ref: models/definitions.yml#/error
+  '429':
+    $ref: ../../shared/responses/too_many_requests.yml
+  '500':
+    $ref: ../../shared/responses/server_error.yml
+  default:
+    $ref: ../../shared/responses/unexpected_error.yml
+x-codeSamples:
+- $ref: examples/curl/agents_cancel_session_workspace_transfer.yml
+security:
+- bearer_auth:
+  - agent_harness_session:operate

specification/resources/agents/agents_commit_session_workspace_transfer.yml

@@ -0,0 +1,93 @@
+operationId: harness_commit_session_workspace_transfer
+summary: Finalize a staged upload.
+description: Upload only. Call once, after all parts have been uploaded. Completes the multipart upload
+  and starts the asynchronous import into the workspace. Responds 202; poll the transfer until `completed`
+  or `failed`.
+tags:
+- Harness Runtime
+parameters:
+- in: path
+  name: session_id
+  required: true
+  description: The session UUID.
+  schema:
+    type: string
+    example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
+  example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
+- in: path
+  name: transfer_id
+  required: true
+  description: The workspace transfer identifier.
+  schema:
+    type: string
+    example: tr_example
+  example: tr_example
+requestBody:
+  required: false
+  content:
+    application/json:
+      schema:
+        type: object
+        properties:
+          sha256:
+            type: string
+            description: Optional lowercase hex SHA-256. Must match the value supplied at create when
+              both are set.
+            example: example
+responses:
+  '202':
+    description: Upload committed; import in progress.
+    headers: &id001
+      ratelimit-limit:
+        $ref: ../../shared/headers.yml#/ratelimit-limit
+      ratelimit-remaining:
+        $ref: ../../shared/headers.yml#/ratelimit-remaining
+      ratelimit-reset:
+        $ref: ../../shared/headers.yml#/ratelimit-reset
+    content:
+      application/json:
+        schema:
+          $ref: models/definitions.yml#/workspace_upload_committed
+  '400':
+    description: Missing transfer_id, sha256 mismatch, or invalid JSON.
+    headers: *id001
+    content:
+      application/json:
+        schema:
+          $ref: models/definitions.yml#/error
+  '401':
+    $ref: ../../shared/responses/unauthorized.yml
+  '404':
+    $ref: ../../shared/responses/not_found.yml
+  '409':
+    description: Transfer is not in a committable state.
+    headers: *id001
+    content:
+      application/json:
+        schema:
+          $ref: models/definitions.yml#/error
+  '501':
+    description: Staged upload is not supported by the active sandbox driver.
+    headers: *id001
+    content:
+      application/json:
+        schema:
+          $ref: models/definitions.yml#/error
+  '423':
+    description: This session is unavailable; contact support.
+    headers: *id001
+    content:
+      application/json:
+        schema:
+          $ref: models/definitions.yml#/error
+  '429':
+    $ref: ../../shared/responses/too_many_requests.yml
+  '500':
+    $ref: ../../shared/responses/server_error.yml
+  default:
+    $ref: ../../shared/responses/unexpected_error.yml
+x-codeSamples:
+- $ref: examples/curl/agents_commit_session_workspace_transfer.yml
+security:
+- bearer_auth:
+  - agent_harness_session:operate

specification/resources/agents/agents_create_config.yml

@@ -0,0 +1,71 @@
+operationId: harness_create_config
+summary: Create an Environment Config (environment spec + optional Insights opt-in).
+description: >-
+  Accepts name, environment-spec YAML text, and optional Insights telemetry opt-in. Tenant secrets
+  are declared inside the environment spec (write-only values), not as sibling request fields.
+  Responses never echo secret values; GET/create may include credential slot metadata
+  (name/source/provider only). Configs are immutable after create.
+tags:
+- Harness Runtime
+requestBody:
+  required: true
+  content:
+    application/json:
+      schema:
+        $ref: models/definitions.yml#/agent_config_create_request
+  description: Environment Config create body. Secret values live in the environment-spec YAML and are never returned.
+responses:
+  '201':
+    description: Config created.
+    headers: &id001
+      ratelimit-limit:
+        $ref: ../../shared/headers.yml#/ratelimit-limit
+      ratelimit-remaining:
+        $ref: ../../shared/headers.yml#/ratelimit-remaining
+      ratelimit-reset:
+        $ref: ../../shared/headers.yml#/ratelimit-reset
+    content:
+      application/json:
+        schema:
+          $ref: models/definitions.yml#/agent_config_response
+  '400':
+    description: Invalid name, JSON wrapper, or environment spec.
+    headers: *id001
+    content:
+      application/json:
+        schema:
+          $ref: models/definitions.yml#/error
+  '401':
+    $ref: ../../shared/responses/unauthorized.yml
+  '409':
+    description: An active config with this name already exists for the team.
+    headers: *id001
+    content:
+      application/json:
+        schema:
+          $ref: models/definitions.yml#/error
+  '413':
+    description: Request body exceeds 1 MiB.
+    headers: *id001
+    content:
+      application/json:
+        schema:
+          $ref: models/definitions.yml#/error
+  '415':
+    description: Content-Type is not application/json.
+    headers: *id001
+    content:
+      application/json:
+        schema:
+          $ref: models/definitions.yml#/error
+  '500':
+    $ref: ../../shared/responses/server_error.yml
+  '429':
+    $ref: ../../shared/responses/too_many_requests.yml
+  default:
+    $ref: ../../shared/responses/unexpected_error.yml
+x-codeSamples:
+- $ref: examples/curl/agents_create_config.yml
+security:
+- bearer_auth:
+  - agent_harness_session:create