From 86953549df2881a7dfadcf16219da13e8952487a Mon Sep 17 00:00:00 2001 From: SSharma-10 Date: Thu, 24 Sep 2026 12:06:27 +0530 Subject: [PATCH 01/16] Add Hosted Agents /v2/agents OpenAPI surface from harness swagger. Document all 38 OHS public endpoints (configs, sessions, checkpoints, fork, workspace transfers, and templates) for client generation and docs. Co-authored-by: Cursor --- specification/DigitalOcean-public.v2.yaml | 123 ++ ...ents_cancel_session_workspace_transfer.yml | 70 + ...ents_commit_session_workspace_transfer.yml | 86 + .../resources/agents/agents_create_config.yml | 69 + .../agents/agents_create_config_clone.yml | 79 + .../agents/agents_create_session.yml | 128 ++ .../agents_create_session_checkpoint.yml | 71 + .../agents/agents_create_session_fork.yml | 71 + .../agents/agents_create_session_input.yml | 72 + ...ate_session_workspace_part_upload_urls.yml | 91 + ...ents_create_session_workspace_transfer.yml | 147 ++ ...agents_create_session_workspace_upload.yml | 131 ++ .../agents/agents_create_template.yml | 46 + .../resources/agents/agents_delete_config.yml | 54 + .../agents/agents_delete_session.yml | 61 + .../agents_delete_session_checkpoint.yml | 58 + .../agents/agents_delete_template.yml | 44 + .../resources/agents/agents_get_config.yml | 52 + .../resources/agents/agents_get_session.yml | 50 + .../agents/agents_get_session_checkpoint.yml | 58 + .../agents_get_session_workspace_download.yml | 128 ++ .../agents_get_session_workspace_transfer.yml | 67 + .../resources/agents/agents_get_template.yml | 44 + .../agents/agents_get_template_build.yml | 53 + .../agents/agents_list_config_sessions.yml | 93 + .../resources/agents/agents_list_configs.yml | 61 + .../agents_list_session_checkpoints.yml | 74 + .../agents_list_session_sandbox_sizes.yml | 37 + .../resources/agents/agents_list_sessions.yml | 91 + .../agents/agents_list_template_builds.yml | 61 + .../agents/agents_list_templates.yml | 50 + .../agents/agents_post_session_hitl.yml | 84 + .../agents/agents_post_session_pause.yml | 76 + .../agents/agents_post_session_resume.yml | 76 + .../agents_post_session_sandbox_exec.yml | 58 + .../agents_revert_session_checkpoint.yml | 72 + .../agents/agents_update_session.yml | 71 + .../agents/agents_update_template.yml | 51 + .../agents/agents_validate_session_policy.yml | 67 + ...ents_cancel_session_workspace_transfer.yml | 4 + ...ents_commit_session_workspace_transfer.yml | 4 + .../examples/curl/agents_create_config.yml | 5 + .../curl/agents_create_config_clone.yml | 3 + .../examples/curl/agents_create_session.yml | 4 + .../curl/agents_create_session_checkpoint.yml | 3 + .../curl/agents_create_session_fork.yml | 3 + .../curl/agents_create_session_input.yml | 4 + ...ate_session_workspace_part_upload_urls.yml | 4 + ...ents_create_session_workspace_transfer.yml | 4 + ...agents_create_session_workspace_upload.yml | 4 + .../examples/curl/agents_create_template.yml | 3 + .../examples/curl/agents_delete_config.yml | 4 + .../examples/curl/agents_delete_session.yml | 4 + .../curl/agents_delete_session_checkpoint.yml | 3 + .../examples/curl/agents_delete_template.yml | 3 + .../examples/curl/agents_get_config.yml | 4 + .../examples/curl/agents_get_session.yml | 4 + .../curl/agents_get_session_checkpoint.yml | 3 + .../agents_get_session_workspace_download.yml | 4 + .../agents_get_session_workspace_transfer.yml | 4 + .../examples/curl/agents_get_template.yml | 3 + .../curl/agents_get_template_build.yml | 3 + .../curl/agents_list_config_sessions.yml | 4 + .../examples/curl/agents_list_configs.yml | 4 + .../curl/agents_list_session_checkpoints.yml | 3 + .../agents_list_session_sandbox_sizes.yml | 4 + .../examples/curl/agents_list_sessions.yml | 4 + .../curl/agents_list_template_builds.yml | 3 + .../examples/curl/agents_list_templates.yml | 3 + .../curl/agents_post_session_hitl.yml | 4 + .../curl/agents_post_session_pause.yml | 4 + .../curl/agents_post_session_resume.yml | 4 + .../curl/agents_post_session_sandbox_exec.yml | 4 + .../curl/agents_revert_session_checkpoint.yml | 3 + .../examples/curl/agents_update_session.yml | 3 + .../examples/curl/agents_update_template.yml | 3 + .../curl/agents_validate_session_policy.yml | 4 + .../resources/agents/models/definitions.yml | 1616 +++++++++++++++++ 78 files changed, 4629 insertions(+) create mode 100644 specification/resources/agents/agents_cancel_session_workspace_transfer.yml create mode 100644 specification/resources/agents/agents_commit_session_workspace_transfer.yml create mode 100644 specification/resources/agents/agents_create_config.yml create mode 100644 specification/resources/agents/agents_create_config_clone.yml create mode 100644 specification/resources/agents/agents_create_session.yml create mode 100644 specification/resources/agents/agents_create_session_checkpoint.yml create mode 100644 specification/resources/agents/agents_create_session_fork.yml create mode 100644 specification/resources/agents/agents_create_session_input.yml create mode 100644 specification/resources/agents/agents_create_session_workspace_part_upload_urls.yml create mode 100644 specification/resources/agents/agents_create_session_workspace_transfer.yml create mode 100644 specification/resources/agents/agents_create_session_workspace_upload.yml create mode 100644 specification/resources/agents/agents_create_template.yml create mode 100644 specification/resources/agents/agents_delete_config.yml create mode 100644 specification/resources/agents/agents_delete_session.yml create mode 100644 specification/resources/agents/agents_delete_session_checkpoint.yml create mode 100644 specification/resources/agents/agents_delete_template.yml create mode 100644 specification/resources/agents/agents_get_config.yml create mode 100644 specification/resources/agents/agents_get_session.yml create mode 100644 specification/resources/agents/agents_get_session_checkpoint.yml create mode 100644 specification/resources/agents/agents_get_session_workspace_download.yml create mode 100644 specification/resources/agents/agents_get_session_workspace_transfer.yml create mode 100644 specification/resources/agents/agents_get_template.yml create mode 100644 specification/resources/agents/agents_get_template_build.yml create mode 100644 specification/resources/agents/agents_list_config_sessions.yml create mode 100644 specification/resources/agents/agents_list_configs.yml create mode 100644 specification/resources/agents/agents_list_session_checkpoints.yml create mode 100644 specification/resources/agents/agents_list_session_sandbox_sizes.yml create mode 100644 specification/resources/agents/agents_list_sessions.yml create mode 100644 specification/resources/agents/agents_list_template_builds.yml create mode 100644 specification/resources/agents/agents_list_templates.yml create mode 100644 specification/resources/agents/agents_post_session_hitl.yml create mode 100644 specification/resources/agents/agents_post_session_pause.yml create mode 100644 specification/resources/agents/agents_post_session_resume.yml create mode 100644 specification/resources/agents/agents_post_session_sandbox_exec.yml create mode 100644 specification/resources/agents/agents_revert_session_checkpoint.yml create mode 100644 specification/resources/agents/agents_update_session.yml create mode 100644 specification/resources/agents/agents_update_template.yml create mode 100644 specification/resources/agents/agents_validate_session_policy.yml create mode 100644 specification/resources/agents/examples/curl/agents_cancel_session_workspace_transfer.yml create mode 100644 specification/resources/agents/examples/curl/agents_commit_session_workspace_transfer.yml create mode 100644 specification/resources/agents/examples/curl/agents_create_config.yml create mode 100644 specification/resources/agents/examples/curl/agents_create_config_clone.yml create mode 100644 specification/resources/agents/examples/curl/agents_create_session.yml create mode 100644 specification/resources/agents/examples/curl/agents_create_session_checkpoint.yml create mode 100644 specification/resources/agents/examples/curl/agents_create_session_fork.yml create mode 100644 specification/resources/agents/examples/curl/agents_create_session_input.yml create mode 100644 specification/resources/agents/examples/curl/agents_create_session_workspace_part_upload_urls.yml create mode 100644 specification/resources/agents/examples/curl/agents_create_session_workspace_transfer.yml create mode 100644 specification/resources/agents/examples/curl/agents_create_session_workspace_upload.yml create mode 100644 specification/resources/agents/examples/curl/agents_create_template.yml create mode 100644 specification/resources/agents/examples/curl/agents_delete_config.yml create mode 100644 specification/resources/agents/examples/curl/agents_delete_session.yml create mode 100644 specification/resources/agents/examples/curl/agents_delete_session_checkpoint.yml create mode 100644 specification/resources/agents/examples/curl/agents_delete_template.yml create mode 100644 specification/resources/agents/examples/curl/agents_get_config.yml create mode 100644 specification/resources/agents/examples/curl/agents_get_session.yml create mode 100644 specification/resources/agents/examples/curl/agents_get_session_checkpoint.yml create mode 100644 specification/resources/agents/examples/curl/agents_get_session_workspace_download.yml create mode 100644 specification/resources/agents/examples/curl/agents_get_session_workspace_transfer.yml create mode 100644 specification/resources/agents/examples/curl/agents_get_template.yml create mode 100644 specification/resources/agents/examples/curl/agents_get_template_build.yml create mode 100644 specification/resources/agents/examples/curl/agents_list_config_sessions.yml create mode 100644 specification/resources/agents/examples/curl/agents_list_configs.yml create mode 100644 specification/resources/agents/examples/curl/agents_list_session_checkpoints.yml create mode 100644 specification/resources/agents/examples/curl/agents_list_session_sandbox_sizes.yml create mode 100644 specification/resources/agents/examples/curl/agents_list_sessions.yml create mode 100644 specification/resources/agents/examples/curl/agents_list_template_builds.yml create mode 100644 specification/resources/agents/examples/curl/agents_list_templates.yml create mode 100644 specification/resources/agents/examples/curl/agents_post_session_hitl.yml create mode 100644 specification/resources/agents/examples/curl/agents_post_session_pause.yml create mode 100644 specification/resources/agents/examples/curl/agents_post_session_resume.yml create mode 100644 specification/resources/agents/examples/curl/agents_post_session_sandbox_exec.yml create mode 100644 specification/resources/agents/examples/curl/agents_revert_session_checkpoint.yml create mode 100644 specification/resources/agents/examples/curl/agents_update_session.yml create mode 100644 specification/resources/agents/examples/curl/agents_update_template.yml create mode 100644 specification/resources/agents/examples/curl/agents_validate_session_policy.yml create mode 100644 specification/resources/agents/models/definitions.yml diff --git a/specification/DigitalOcean-public.v2.yaml b/specification/DigitalOcean-public.v2.yaml index a14a06c72..8c739a15c 100644 --- a/specification/DigitalOcean-public.v2.yaml +++ b/specification/DigitalOcean-public.v2.yaml @@ -65,6 +65,24 @@ tags: Discover Action Gateway tools and providers, manage versioned toolbelts and OAuth connections, and create policy-bound sessions for end users. + - name: Agents + description: |- + Hosted Agents API under `/v2/agents`. Sessions (`/v2/agents/sessions`) + represent a managed agent + sandbox pair. Product provenance is exposed + via `session.origin` (`direct` | `simulation` | `evaluation`). ListSessions + omits simulation and evaluation sessions server-side so customer surfaces + stay free of product-owned internal runs; GetSession by session_id still + returns those sessions for the owning product workflow. + + Agent Configs (`/v2/agents/configs`) are immutable team-scoped manifests + that sessions can be created from. Soft-delete releases the active name + while keeping `config_id` resolvable for existing sessions; clone copies a + sanitized manifest 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 @@ -882,6 +900,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" diff --git a/specification/resources/agents/agents_cancel_session_workspace_transfer.yml b/specification/resources/agents/agents_cancel_session_workspace_transfer.yml new file mode 100644 index 000000000..504138b3d --- /dev/null +++ b/specification/resources/agents/agents_cancel_session_workspace_transfer.yml @@ -0,0 +1,70 @@ +operationId: agents_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: +- Agents +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 + '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: + - agents:create diff --git a/specification/resources/agents/agents_commit_session_workspace_transfer.yml b/specification/resources/agents/agents_commit_session_workspace_transfer.yml new file mode 100644 index 000000000..22bfae572 --- /dev/null +++ b/specification/resources/agents/agents_commit_session_workspace_transfer.yml @@ -0,0 +1,86 @@ +operationId: agents_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: +- Agents +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 + '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: + - agents:create diff --git a/specification/resources/agents/agents_create_config.yml b/specification/resources/agents/agents_create_config.yml new file mode 100644 index 000000000..5b2f54e41 --- /dev/null +++ b/specification/resources/agents/agents_create_config.yml @@ -0,0 +1,69 @@ +operationId: agents_create_config +summary: Create an Agent Config (manifest + secrets in one request). +description: Accepts name, agents.yaml text, and optional write-only secret values in one request. Responses + never echo secret values; GET/create may include credential slot metadata (name/source/provider only). Configs + are immutable after create. +tags: +- Agents +requestBody: + required: true + content: + application/json: + schema: + $ref: models/definitions.yml#/agent_config_create_request + description: Unified Agent Config create body. secrets/oauth_assignments are write-only and 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 agents.yaml manifest. + 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: + - agents:create diff --git a/specification/resources/agents/agents_create_config_clone.yml b/specification/resources/agents/agents_create_config_clone.yml new file mode 100644 index 000000000..0824c7920 --- /dev/null +++ b/specification/resources/agents/agents_create_config_clone.yml @@ -0,0 +1,79 @@ +operationId: agents_create_config_clone +summary: Clone an Agent Config under a new name. +description: 'Copies the source config''s sanitized manifest to a new UUID. Source and clone are independent (no lineage). Credential bindings are never copied: if the manifest declares secret slots, supply secrets/oauth_assignments again (write-only). content_hash matches the source when the manifest is unchanged.' +tags: +- Agents +parameters: +- in: path + name: config_id + required: true + description: The Agent Config UUID. + schema: + type: string + format: uuid + example: 019fb39c-14d9-7080-933e-b9b90e25acda + example: 019fb39c-14d9-7080-933e-b9b90e25acda +requestBody: + required: true + content: + application/json: + schema: + $ref: models/definitions.yml#/agent_config_clone_request + description: Clone body with required new name plus write-only credentials for any declared slots. +responses: + '201': + description: Clone 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, missing credential slots, or source manifest fails current durable validation.' + 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 + '404': + $ref: ../../shared/responses/not_found.yml + '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_clone.yml +security: +- bearer_auth: + - agents:create diff --git a/specification/resources/agents/agents_create_session.yml b/specification/resources/agents/agents_create_session.yml new file mode 100644 index 000000000..5e4ac00af --- /dev/null +++ b/specification/resources/agents/agents_create_session.yml @@ -0,0 +1,128 @@ +operationId: agents_create_session +summary: CreateSession provisions a sandbox and starts the requested agent. +description: 'Returns once the session row is allocated. The sandbox boot completes asynchronously; clients + observe SESSION_STATUS_PROVISIONING → READY via StreamSession. + + + Two mutually exclusive request forms are selected by Content-Type. Existing YAML callers send a raw + customer `agents.yaml` Agent manifest with `application/x-yaml`, `application/yaml`, `text/yaml`, or + `text/x-yaml`; this flow is unchanged. Definition-backed callers send the strict `CreateSessionDefinitionRequest` + JSON object with `application/json`. Unknown JSON fields, including team identity, are rejected. An + omitted revision_id pins the definition''s current immutable revision. + + + Definition-backed execution requires an exactly matching credential binding set when the selected revision + declares logical secrets. Static values are fetched only by their persisted name/region/version and + are never returned or persisted. OAuth bindings currently fail closed with 501. + + + Every successful create atomically persists value-free execution provenance and an allowlisted agent-spec + audit snapshot. The team and user identity are taken from the authenticated principal, never the body. + `X-Device-UUID` (if present) is persisted on the session row.' +tags: +- Agents +parameters: +- in: header + name: X-Device-UUID + required: false + description: Optional hardware device id forwarded by doctl. Persisted on the session row for lifecycle + attribution. Values over 128 bytes are ignored. + schema: + type: string + example: device-uuid-example + example: device-uuid-example +requestBody: + required: true + content: + application/json: + schema: + $ref: models/definitions.yml#/create_session_definition_request + application/x-yaml: &id001 + schema: + $ref: models/definitions.yml#/agent_manifest + application/yaml: *id001 + text/yaml: *id001 + text/x-yaml: *id001 + description: Either a raw AgentManifest with a YAML Content-Type or CreateSessionDefinitionRequest with + application/json. The forms are mutually exclusive by Content-Type. +responses: + '200': + description: Session row allocated; sandbox boot continues asynchronously. + headers: &id002 + 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#/create_session_response + '400': + description: Invalid manifest/reference JSON, incompatible or missing binding set, env collision, + credential limit violation, or invalid session/origin identifier. + headers: *id002 + content: + application/json: + schema: + $ref: models/definitions.yml#/error + '401': + $ref: ../../shared/responses/unauthorized.yml + '403': + description: Secrets Manager denied access to a pinned credential. + headers: *id002 + content: + application/json: + schema: + $ref: models/definitions.yml#/error + '409': + description: Team is at the active-session quota, a live session name already exists, or the binding + set targets another revision. + headers: *id002 + content: + application/json: + schema: + $ref: models/definitions.yml#/error + '404': + $ref: ../../shared/responses/not_found.yml + '413': + description: JSON reference body exceeds 16 KiB or YAML body exceeds 1 MiB. + headers: *id002 + content: + application/json: + schema: + $ref: models/definitions.yml#/error + '415': + description: Unsupported Content-Type. + headers: *id002 + content: + application/json: + schema: + $ref: models/definitions.yml#/error + '501': + description: The selected binding set contains an OAuth assignment; execution-time OAuth brokering + is not available yet. + headers: *id002 + content: + application/json: + schema: + $ref: models/definitions.yml#/error + '503': + description: Secrets Manager is unavailable. + headers: *id002 + 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_session.yml +security: +- bearer_auth: + - agents:create diff --git a/specification/resources/agents/agents_create_session_checkpoint.yml b/specification/resources/agents/agents_create_session_checkpoint.yml new file mode 100644 index 000000000..3b347bce6 --- /dev/null +++ b/specification/resources/agents/agents_create_session_checkpoint.yml @@ -0,0 +1,71 @@ +operationId: agents_create_session_checkpoint +summary: CreateCheckpoint captures the session's live sandbox state as a durable checkpoint. +description: 'Synchronous: blocks until the capture reaches READY and returns the terminal Checkpoint — clients never see PENDING on this endpoint and need no poll loop. The checkpoint binds the machine-state capture to the event-log cursor at the cut, so it can later seed forks (POST .../fork) and rollback. Checkpoints are taken between turns; a session with an active turn in flight returns 409.' +tags: +- Agents +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 +requestBody: + required: false + content: + application/json: + schema: + $ref: models/definitions.yml#/create_checkpoint_request + description: Optional; an empty or omitted body creates an unlabeled checkpoint. +responses: + '200': + description: 'Checkpoint captured. The returned checkpoint is terminal (status READY).' + 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#/create_checkpoint_response + '401': + $ref: ../../shared/responses/unauthorized.yml + '403': + description: Session belongs to another team. + headers: *id001 + content: + application/json: + schema: + $ref: models/definitions.yml#/error + '404': + $ref: ../../shared/responses/not_found.yml + '409': + description: 'Session busy (an active turn is in flight), session not running, or team checkpoint storage quota exceeded.' + headers: *id001 + content: + application/json: + schema: + $ref: models/definitions.yml#/error + '501': + description: Checkpoints are not supported for this agent/substrate. + 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_session_checkpoint.yml +security: +- bearer_auth: + - agents:create diff --git a/specification/resources/agents/agents_create_session_fork.yml b/specification/resources/agents/agents_create_session_fork.yml new file mode 100644 index 000000000..dd2a84134 --- /dev/null +++ b/specification/resources/agents/agents_create_session_fork.yml @@ -0,0 +1,71 @@ +operationId: agents_create_session_fork +summary: ForkSession creates child sessions from a checkpoint of this session. +description: 'Each child boots a fresh sandbox from the checkpoint''s machine-state capture and is drivable exactly like any other session (input, HITL), with parent_session_id and fork_id set for lineage. When from_checkpoint_id is omitted, an implicit checkpoint of the session "now" is captured first and the children fork from that. All-or-nothing: on failure nothing is left running.' +tags: +- Agents +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 +requestBody: + required: false + content: + application/json: + schema: + $ref: models/definitions.yml#/fork_session_request + description: 'Optional; an empty or omitted body forks a single child from an implicit checkpoint of "now".' +responses: + '200': + description: 'The created child sessions (each a full Session, PROVISIONING -> READY).' + 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#/fork_session_response + '401': + $ref: ../../shared/responses/unauthorized.yml + '403': + description: Session belongs to another team. + headers: *id001 + content: + application/json: + schema: + $ref: models/definitions.yml#/error + '404': + $ref: ../../shared/responses/not_found.yml + '409': + description: 'Team is at the active-session quota, the checkpoint is not READY, or the source session is itself a fork.' + headers: *id001 + content: + application/json: + schema: + $ref: models/definitions.yml#/error + '501': + description: Forking is not supported for this agent/substrate. + 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_session_fork.yml +security: +- bearer_auth: + - agents:create diff --git a/specification/resources/agents/agents_create_session_input.yml b/specification/resources/agents/agents_create_session_input.yml new file mode 100644 index 000000000..c9985cb3e --- /dev/null +++ b/specification/resources/agents/agents_create_session_input.yml @@ -0,0 +1,72 @@ +operationId: agents_create_session_input +summary: SendInput delivers a user chat message into the session. +description: The agent observes it on its next turn and emits subsequent events via StreamSession. The + input is forwarded to the owning microVM's OHR inbound surface, which attributes it to a run and returns + the run id. +tags: +- Agents +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 +requestBody: + required: true + content: + application/json: + schema: + $ref: models/definitions.yml#/send_input_request +responses: + '200': + description: Input accepted and attributed to a run. + 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#/send_input_response + '400': + description: Malformed JSON or empty text. + headers: *id001 + content: + application/json: + schema: + $ref: models/definitions.yml#/error + '401': + $ref: ../../shared/responses/unauthorized.yml + '403': + description: Session belongs to another team. + headers: *id001 + content: + application/json: + schema: + $ref: models/definitions.yml#/error + '404': + $ref: ../../shared/responses/not_found.yml + '409': + description: Session is not in a state that accepts input (not READY/DETACHED, or has no sandbox). + 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_session_input.yml +security: +- bearer_auth: + - agents:create diff --git a/specification/resources/agents/agents_create_session_workspace_part_upload_urls.yml b/specification/resources/agents/agents_create_session_workspace_part_upload_urls.yml new file mode 100644 index 000000000..88b5db44e --- /dev/null +++ b/specification/resources/agents/agents_create_session_workspace_part_upload_urls.yml @@ -0,0 +1,91 @@ +operationId: agents_create_session_workspace_part_upload_urls +summary: Mint presigned PUT URLs for one or more multipart upload parts. +description: Upload only. Pass one or more 1-based `part_numbers`; the response returns a presigned `upload_url` + per part (all sharing one `expires_at`), so a client can drive parallel part uploads without a round + trip per part. PUT each part's bytes directly to its URL (bypassing harness-api). If URLs expire before + the PUT, request them again. +tags: +- Agents +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: true + content: + application/json: + schema: + type: object + required: + - part_numbers + properties: + part_numbers: + type: array + items: + type: integer + format: int32 + example: 1 + description: 1-based part indices to presign (single or batched). +responses: + '200': + description: Presigned PUT URLs for the requested parts. + 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_part_upload_urls + '400': + description: Missing transfer_id, empty part_numbers, or a part number < 1, 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 state that accepts part uploads. + 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 + '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_create_session_workspace_part_upload_urls.yml +security: +- bearer_auth: + - agents:create diff --git a/specification/resources/agents/agents_create_session_workspace_transfer.yml b/specification/resources/agents/agents_create_session_workspace_transfer.yml new file mode 100644 index 000000000..2113f4d4c --- /dev/null +++ b/specification/resources/agents/agents_create_session_workspace_transfer.yml @@ -0,0 +1,147 @@ +operationId: agents_create_session_workspace_transfer +summary: Start a staged (large-file) workspace transfer. +description: 'Creates an asynchronous, object-storage-backed transfer for payloads larger than the streaming + path supports (> ~50 MiB). Bulk bytes never traverse harness-api: the client PUTs/GETs presigned DO + Spaces URLs directly. + + + Set `direction` to `upload` or `download`. + + - `upload`: responds 201 with `transfer_id` + `part_size`; the client then requests per-part presigned + PUT URLs, uploads them to Spaces, and calls `commit`. + + - `download`: responds 202 with `transfer_id`; the client polls GET until `completed` and then fetches + `download_url` from Spaces. + + + Upload and cancel currently return 501 until the sandbox backend RPCs ship; download is live.' +tags: +- Agents +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 +requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - direction + - path + properties: + direction: + type: string + enum: + - upload + - download + description: Transfer direction. + example: upload + path: + type: string + description: Workspace-relative path. Destination for upload, source for download. Paths that + escape the workspace root are rejected. + example: example + is_archive: + type: boolean + description: Upload only. When true, the payload is a tar the guest extracts at `path`. + example: true + as_archive: + type: boolean + description: Download only. When true, `path` is exported as a tar stream. + example: true + size_bytes: + type: string + format: int64 + description: Optional total payload size. Validated against the maximum staged object size + (50 GiB); a larger value returns 413. + example: example + sha256: + type: string + description: Optional lowercase hex SHA-256 of the full payload. If set on an upload, it must + match on commit. + example: example +responses: + '201': + description: Upload transfer created; proceed to request part upload URLs. + 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_created + '202': + description: Download transfer accepted; poll the transfer until completed. + headers: *id001 + content: + application/json: + schema: + $ref: models/definitions.yml#/workspace_transfer_created + '400': + description: Missing/invalid direction or path, or invalid JSON. + headers: *id001 + content: + application/json: + schema: + $ref: models/definitions.yml#/error + '401': + $ref: ../../shared/responses/unauthorized.yml + '403': + description: Path resolves outside the workspace, or the session belongs to another team. + headers: *id001 + content: + application/json: + schema: + $ref: models/definitions.yml#/error + '404': + $ref: ../../shared/responses/not_found.yml + '409': + description: Session has no sandbox, or the sandbox is not ready. + headers: *id001 + content: + application/json: + schema: + $ref: models/definitions.yml#/error + '413': + description: Declared size exceeds the maximum staged object size. + headers: *id001 + content: + application/json: + schema: + $ref: models/definitions.yml#/error + '501': + description: Staged transfer (or this direction) is not supported by the active sandbox driver. + headers: *id001 + content: + application/json: + schema: + $ref: models/definitions.yml#/error + '502': + description: Upstream sandbox transfer coordination failed. + 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_create_session_workspace_transfer.yml +security: +- bearer_auth: + - agents:create diff --git a/specification/resources/agents/agents_create_session_workspace_upload.yml b/specification/resources/agents/agents_create_session_workspace_upload.yml new file mode 100644 index 000000000..280237549 --- /dev/null +++ b/specification/resources/agents/agents_create_session_workspace_upload.yml @@ -0,0 +1,131 @@ +operationId: agents_create_session_workspace_upload +summary: Upload a file or tar archive into the session's sandbox workspace. +description: Streams the raw request body to a path inside the sandbox workspace. Concurrent transfers + (upload + download) are capped server-side; over the cap the request blocks and may return 503. The + optional `X-Content-Sha256` request header carries a hex digest the guest verifies after the full payload + is written. +tags: +- Agents +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: query + name: path + required: true + description: Destination path inside the sandbox workspace. Relative paths resolve under the workspace + root; paths that escape the workspace are rejected. Required. + schema: + type: string + example: example + example: example +- in: query + name: is_archive + required: false + description: If true, the body is a tar stream that the guest extracts under `path`. Defaults to false + (single file). + schema: + type: boolean + example: true + example: true +- in: header + name: X-Content-Sha256 + required: false + description: Optional hex SHA-256 of the full payload. The guest verifies it after writing; a mismatch + returns 400. + schema: + type: string + example: example + example: example +requestBody: + required: true + content: + application/octet-stream: + schema: + type: string + format: binary + example: example + description: Raw file bytes (or tar stream when is_archive=true). Capped at 500 MiB. +responses: + '200': + description: Upload committed. + 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_response + '400': + description: Missing path, invalid query parameter, invalid path, or SHA-256 mismatch. + headers: *id001 + content: + application/json: + schema: + $ref: models/definitions.yml#/error + '401': + $ref: ../../shared/responses/unauthorized.yml + '403': + description: Path resolves outside the workspace, or the session belongs to another team. + headers: *id001 + content: + application/json: + schema: + $ref: models/definitions.yml#/error + '404': + $ref: ../../shared/responses/not_found.yml + '409': + description: Session has no sandbox, or the sandbox is not ready. + headers: *id001 + content: + application/json: + schema: + $ref: models/definitions.yml#/error + '413': + description: Payload exceeds the maximum allowed size. + headers: *id001 + content: + application/json: + schema: + $ref: models/definitions.yml#/error + '501': + description: Workspace file transfer is not supported by the active sandbox driver. + headers: *id001 + content: + application/json: + schema: + $ref: models/definitions.yml#/error + '502': + description: Upstream sandbox transfer failed. + headers: *id001 + content: + application/json: + schema: + $ref: models/definitions.yml#/error + '503': + description: Workspace transfer capacity exhausted; retry later. + 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_create_session_workspace_upload.yml +security: +- bearer_auth: + - agents:create diff --git a/specification/resources/agents/agents_create_template.yml b/specification/resources/agents/agents_create_template.yml new file mode 100644 index 000000000..c4231aee9 --- /dev/null +++ b/specification/resources/agents/agents_create_template.yml @@ -0,0 +1,46 @@ +operationId: agents_create_template +summary: CreateTemplate creates a team custom template and kicks a build. +description: Creates a team-owned template from a customer OCI ref rebased onto a base template. team_id is stamped from the authenticated principal. +tags: +- Agents +requestBody: + required: true + content: + application/json: + schema: + $ref: models/definitions.yml#/create_template_request + description: Template create body. +responses: + '201': + description: Template created; build kicked. + 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#/create_template_response + '400': + description: Invalid request. + headers: *id001 + content: + application/json: + schema: + $ref: models/definitions.yml#/error + '401': + $ref: ../../shared/responses/unauthorized.yml + '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_template.yml +security: +- bearer_auth: + - agents:create diff --git a/specification/resources/agents/agents_delete_config.yml b/specification/resources/agents/agents_delete_config.yml new file mode 100644 index 000000000..b9150bc45 --- /dev/null +++ b/specification/resources/agents/agents_delete_config.yml @@ -0,0 +1,54 @@ +operationId: agents_delete_config +summary: Soft-delete an Agent Config. +description: Releases the active team-scoped name; the config row is retained (soft delete), so sessions + created from it keep a resolvable config_id. +tags: +- Agents +parameters: +- in: path + name: config_id + required: true + description: The Agent Config UUID. + schema: + type: string + format: uuid + example: 019fb39c-14d9-7080-933e-b9b90e25acda + example: 019fb39c-14d9-7080-933e-b9b90e25acda +responses: + '204': + description: Config soft-deleted; no response body. + headers: + ratelimit-limit: + $ref: ../../shared/headers.yml#/ratelimit-limit + ratelimit-remaining: + $ref: ../../shared/headers.yml#/ratelimit-remaining + ratelimit-reset: + $ref: ../../shared/headers.yml#/ratelimit-reset + '400': + description: config_id is not a UUID. + headers: + 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#/error + '401': + $ref: ../../shared/responses/unauthorized.yml + '404': + $ref: ../../shared/responses/not_found.yml + '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_delete_config.yml +security: +- bearer_auth: + - agents:delete diff --git a/specification/resources/agents/agents_delete_session.yml b/specification/resources/agents/agents_delete_session.yml new file mode 100644 index 000000000..fab9dadcb --- /dev/null +++ b/specification/resources/agents/agents_delete_session.yml @@ -0,0 +1,61 @@ +operationId: agents_delete_session +summary: DestroySession tears down the sandbox and marks the session DESTROYED. +description: Persistent workspace contents are retained per tenant policy. Returns 204 No Content on success. +tags: +- Agents +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: header + name: X-Device-UUID + required: false + description: Optional hardware device id forwarded by doctl. Recorded on the session row as the device + that performed the destroy. + schema: + type: string + example: device-uuid-example + example: device-uuid-example +responses: + '204': + description: Session destroyed; no response body. + headers: + ratelimit-limit: + $ref: ../../shared/headers.yml#/ratelimit-limit + ratelimit-remaining: + $ref: ../../shared/headers.yml#/ratelimit-remaining + ratelimit-reset: + $ref: ../../shared/headers.yml#/ratelimit-reset + '401': + $ref: ../../shared/responses/unauthorized.yml + '403': + description: Session belongs to another team. + headers: + 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#/error + '404': + $ref: ../../shared/responses/not_found.yml + '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_delete_session.yml +security: +- bearer_auth: + - agents:delete diff --git a/specification/resources/agents/agents_delete_session_checkpoint.yml b/specification/resources/agents/agents_delete_session_checkpoint.yml new file mode 100644 index 000000000..2ffaf615a --- /dev/null +++ b/specification/resources/agents/agents_delete_session_checkpoint.yml @@ -0,0 +1,58 @@ +operationId: agents_delete_session_checkpoint +summary: DeleteCheckpoint removes a checkpoint and its underlying machine-state capture. +description: 'Idempotent: deleting an already-gone checkpoint still returns 200. Removes the DB row and the substrate checkpoint.' +tags: +- Agents +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: checkpoint_id + required: true + description: The checkpoint id. + schema: + type: string + example: cp_9f2c1a4b + example: cp_9f2c1a4b +responses: + '200': + description: Checkpoint deleted. + 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#/delete_checkpoint_response + '401': + $ref: ../../shared/responses/unauthorized.yml + '403': + description: Session belongs to another team. + headers: *id001 + content: + application/json: + schema: + $ref: models/definitions.yml#/error + '404': + $ref: ../../shared/responses/not_found.yml + '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_delete_session_checkpoint.yml +security: +- bearer_auth: + - agents:delete diff --git a/specification/resources/agents/agents_delete_template.yml b/specification/resources/agents/agents_delete_template.yml new file mode 100644 index 000000000..80871832a --- /dev/null +++ b/specification/resources/agents/agents_delete_template.yml @@ -0,0 +1,44 @@ +operationId: agents_delete_template +summary: DeleteTemplate deletes a team custom template. +description: Global templates cannot be deleted via this API. +tags: +- Agents +parameters: +- in: path + name: template_id + required: true + description: The template UUID. + schema: + type: string + format: uuid + example: 11111111-2222-3333-4444-555555555555 + example: 11111111-2222-3333-4444-555555555555 +responses: + '200': + description: Template deleted. + 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#/delete_template_response + '401': + $ref: ../../shared/responses/unauthorized.yml + '404': + $ref: ../../shared/responses/not_found.yml + '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_delete_template.yml +security: +- bearer_auth: + - agents:delete diff --git a/specification/resources/agents/agents_get_config.yml b/specification/resources/agents/agents_get_config.yml new file mode 100644 index 000000000..31d1841aa --- /dev/null +++ b/specification/resources/agents/agents_get_config.yml @@ -0,0 +1,52 @@ +operationId: agents_get_config +summary: Get an active Agent Config and its manifest. +description: Returns one team-scoped Agent Config including the sanitized manifest and redacted credential + slot metadata. Secret values are never returned. +tags: +- Agents +parameters: +- in: path + name: config_id + required: true + description: The Agent Config UUID. + schema: + type: string + format: uuid + example: 019fb39c-14d9-7080-933e-b9b90e25acda + example: 019fb39c-14d9-7080-933e-b9b90e25acda +responses: + '200': + description: The team-scoped config. + 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: config_id is not a UUID. + headers: *id001 + content: + application/json: + schema: + $ref: models/definitions.yml#/error + '401': + $ref: ../../shared/responses/unauthorized.yml + '404': + $ref: ../../shared/responses/not_found.yml + '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_get_config.yml +security: +- bearer_auth: + - agents:read diff --git a/specification/resources/agents/agents_get_session.yml b/specification/resources/agents/agents_get_session.yml new file mode 100644 index 000000000..8f9ab01a2 --- /dev/null +++ b/specification/resources/agents/agents_get_session.yml @@ -0,0 +1,50 @@ +operationId: agents_get_session +summary: GetSession returns the current snapshot of a session. +description: GetSession returns the current snapshot of a session. +tags: +- Agents +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 +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_session_response + '401': + $ref: ../../shared/responses/unauthorized.yml + '403': + description: Session belongs to another team. + headers: *id001 + content: + application/json: + schema: + $ref: models/definitions.yml#/error + '404': + $ref: ../../shared/responses/not_found.yml + '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_get_session.yml +security: +- bearer_auth: + - agents:read diff --git a/specification/resources/agents/agents_get_session_checkpoint.yml b/specification/resources/agents/agents_get_session_checkpoint.yml new file mode 100644 index 000000000..40d6054a3 --- /dev/null +++ b/specification/resources/agents/agents_get_session_checkpoint.yml @@ -0,0 +1,58 @@ +operationId: agents_get_session_checkpoint +summary: GetCheckpoint returns the current snapshot of a checkpoint. +description: GetCheckpoint returns the current snapshot of a checkpoint. +tags: +- Agents +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: checkpoint_id + required: true + description: The checkpoint id. + schema: + type: string + example: cp_9f2c1a4b + example: cp_9f2c1a4b +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_checkpoint_response + '401': + $ref: ../../shared/responses/unauthorized.yml + '403': + description: Session belongs to another team. + headers: *id001 + content: + application/json: + schema: + $ref: models/definitions.yml#/error + '404': + $ref: ../../shared/responses/not_found.yml + '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_get_session_checkpoint.yml +security: +- bearer_auth: + - agents:read diff --git a/specification/resources/agents/agents_get_session_workspace_download.yml b/specification/resources/agents/agents_get_session_workspace_download.yml new file mode 100644 index 000000000..63f1643e4 --- /dev/null +++ b/specification/resources/agents/agents_get_session_workspace_download.yml @@ -0,0 +1,128 @@ +operationId: agents_get_session_workspace_download +summary: Download a file or tar archive from the session's sandbox workspace. +description: 'Streams the workspace payload back as `application/octet-stream` using chunked transfer + encoding, followed by a fixed integrity footer. + + + Response body layout: `` + `