Add Hosted Agents /v2/agents OpenAPI (triggers, event stream, port-forward; supersedes #1233)

specification/DigitalOcean-public.v2.yaml

@@ -84,6 +84,29 @@ 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.
+
+      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.
+
   - name: Apps
     description: |-
       App Platform is a Platform-as-a-Service (PaaS) offering from DigitalOcean that allows
@@ -768,6 +791,7 @@ x-tagGroups:
       - Floating IP Actions
       - Floating IPs
       - Functions
+      - Harness Runtime
       - Image Actions
       - Images
       - Insights
@@ -1022,6 +1046,156 @@ 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/sessions/{session_id}/events:
+    get:
+      $ref: "resources/agents/agents_stream_session_events.yml"
+  /v2/agents/sessions/{session_id}/port-forward/{port}:
+    get:
+      $ref: "resources/agents/agents_port_forward_session.yml"
+  /v2/agents/sessions/{session_id}/ingress:
+    get:
+      $ref: "resources/agents/agents_get_session_ingress.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/agents/triggers:
+    get:
+      $ref: "resources/agents/agents_list_triggers.yml"
+    post:
+      $ref: "resources/agents/agents_create_trigger.yml"
+  /v2/agents/triggers/by-session/{session_id}:
+    get:
+      $ref: "resources/agents/agents_get_trigger_by_session.yml"
+  /v2/agents/triggers/reusable-sessions:
+    get:
+      $ref: "resources/agents/agents_list_reusable_sessions.yml"
+  /v2/agents/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:
+    get:
+      $ref: "resources/agents/agents_list_trigger_executions.yml"
+  /v2/agents/triggers/{trigger_id}/executions/{execution_id}:
+    get:
+      $ref: "resources/agents/agents_get_trigger_execution.yml"
+  /v2/agents/triggers/{trigger_id}/executions/{execution_id}/cancel:
+    post:
+      $ref: "resources/agents/agents_cancel_trigger_execution.yml"
+  /v2/agents/triggers/{trigger_id}/rotate-secret:
+    post:
+      $ref: "resources/agents/agents_rotate_trigger_secret.yml"
+  /v2/agents/triggers/{trigger_id}/webhook:
+    post:
+      $ref: "resources/agents/agents_receive_trigger_webhook.yml"
+  /v2/agents/webhook-providers:
+    get:
+      $ref: "resources/agents/agents_list_webhook_providers.yml"
+
   /v2/apps:
     get:
       $ref: "resources/apps/apps_list.yml"

specification/resources/agents/agents_cancel_session_workspace_transfer.yml

@@ -0,0 +1,84 @@
+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
+  '402':
+    description: The team is blocked by the prepayment gate.
+    headers: *id001
+    content:
+      application/json:
+        schema:
+          $ref: models/definitions.yml#/error
+  '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_cancel_trigger_execution.yml

@@ -0,0 +1,72 @@
+operationId: harness_cancel_trigger_execution
+summary: CancelExecution ends a running execution and frees the trigger's in-flight slot.
+description: Fails the execution and frees the trigger's in-flight slot. A fresh-mode session is
+  destroyed outright. A reuse-mode session is only paused, not stopped - harness has no run-interrupt
+  call, so the agent's turn may still be in flight server-side; this frees the queue, not necessarily
+  the agent's work. A non-running execution is a no-op that still returns 200.
+tags:
+- Harness Runtime
+parameters:
+- in: path
+  name: trigger_id
+  required: true
+  description: The trigger UUID.
+  schema:
+    type: string
+    example: b1a0c6de-1f2e-4a3b-9c8d-0e1f2a3b4c5d
+  example: b1a0c6de-1f2e-4a3b-9c8d-0e1f2a3b4c5d
+- in: path
+  name: execution_id
+  required: true
+  description: The execution UUID.
+  schema:
+    type: string
+    example: 7c1f9e2a-3b4c-5d6e-7f80-91a2b3c4d5e6
+  example: 7c1f9e2a-3b4c-5d6e-7f80-91a2b3c4d5e6
+- in: query
+  name: force
+  required: false
+  description: Cancel even if the execution has not started a run yet (the worker's own dispatch may
+    still be in flight). Without this, that case returns 409; reclaim clears it automatically within
+    15m regardless.
+  schema:
+    type: boolean
+    example: false
+  example: false
+responses:
+  '200':
+    description: A successful response.
+    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#/get_trigger_execution_response
+  '401':
+    $ref: ../../shared/responses/unauthorized.yml
+  '404':
+    $ref: ../../shared/responses/not_found.yml
+  '409':
+    description: Execution has not started a run yet (the worker's dispatch is still in flight); retry
+      shortly, or pass force=true.
+    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_cancel_trigger_execution.yml
+security:
+- bearer_auth:
+  - agent_harness_session:operate