diff --git a/specification/DigitalOcean-public.v2.yaml b/specification/DigitalOcean-public.v2.yaml index 51cb1b467..aaff6735c 100644 --- a/specification/DigitalOcean-public.v2.yaml +++ b/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" 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..33569ccbe --- /dev/null +++ b/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 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..bf88277d0 --- /dev/null +++ b/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 diff --git a/specification/resources/agents/agents_create_config.yml b/specification/resources/agents/agents_create_config.yml new file mode 100644 index 000000000..179ab3f9c --- /dev/null +++ b/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 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..e810a7b3a --- /dev/null +++ b/specification/resources/agents/agents_create_config_clone.yml @@ -0,0 +1,79 @@ +operationId: harness_create_config_clone +summary: Clone an Environment 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: +- Harness Runtime +parameters: +- in: path + name: config_id + required: true + description: The Environment 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 environment spec 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: + - agent_harness_session: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..d354bd935 --- /dev/null +++ b/specification/resources/agents/agents_create_session.yml @@ -0,0 +1,143 @@ +operationId: harness_create_session +summary: CreateSession provisions a sandbox and starts a Harness Runtime session. +description: |- + Returns once the session row is allocated. Sandbox boot completes asynchronously. + + Two mutually exclusive request forms are selected by Content-Type (same contract as + harness-api `harness.swagger.json`): + - YAML (`application/x-yaml`, `application/yaml`, `text/yaml`, `text/x-yaml`): the environment + spec. Two environment-spec formats are accepted during the dual-format transition: the flat + format (primary) and the legacy `agents.digitalocean.com/v1alpha1` envelope (deprecated). A + top-level `apiVersion` key selects the legacy parser; its absence selects flat. Internally + persists a durable Environment Config, then creates the session. + - JSON (`application/json`): `{name, config_id}` loads the config, resolves its credentials from + Secrets Manager at the version pinned when the config was created, and creates the session. + + The OpenAPI `requestBody` schemas the JSON form for client generation (Autorest cannot emit a + multi–content-type body). The live API still accepts the YAML forms listed above. + + Successful responses may include `config_id` on the session. `X-Device-UUID` (if present) is + persisted on the session row. Query parameters `openai_session_id` and `resume_on_topoff` apply to + both forms; when both the JSON body field and `?resume_on_topoff=` are present, the query + parameter wins. +tags: +- Harness Runtime +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 +- in: query + name: openai_session_id + required: false + description: 'OpenAI Agents API session id (sess_…) for adapter: codex-agentapi. doctl creates the OpenAI + session before calling DO and passes the resulting id here; harness-api persists it for correlation. + Empty/omitted for every other agent kind.' + schema: + type: string + example: sess_abc123 + example: sess_abc123 +- in: query + name: resume_on_topoff + required: false + description: Opt the new session in to automatic resumption when the team's prepayment balance is restored. + Defaults to false. Exists as a query parameter so the environment spec (YAML body) form can carry it too. + On the application/json form the body field is idiomatic, but this parameter wins when both are present. + Must be exactly one of true/false/1/0; anything else is a 400. + schema: + type: boolean + example: false + example: false +requestBody: + required: true + description: |- + CreateSessionConfigRequest with `application/json`. The live API also accepts a raw environment + spec under YAML Content-Types (see operation description); those forms are omitted from `content` + so generated clients (pydo/autorest) can emit this operation. + content: + application/json: + schema: + $ref: models/definitions.yml#/create_session_config_request +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/config JSON, incompatible credentials, or invalid query parameter. + 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 + '404': + $ref: ../../shared/responses/not_found.yml + '409': + description: Team is at the active-session quota, or a live session name already exists. + headers: *id002 + content: + application/json: + schema: + $ref: models/definitions.yml#/error + '413': + description: JSON 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 + '500': + $ref: ../../shared/responses/server_error.yml + '501': + description: Requested capability is not available. + 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 + '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: + - agent_harness_session: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..7d9138f4a --- /dev/null +++ b/specification/resources/agents/agents_create_session_checkpoint.yml @@ -0,0 +1,78 @@ +operationId: harness_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: +- 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 +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 + '423': + description: This session is unavailable; contact support. + 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: + - agent_harness_session:operate 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..aec12fa80 --- /dev/null +++ b/specification/resources/agents/agents_create_session_fork.yml @@ -0,0 +1,78 @@ +operationId: harness_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: +- 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 +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 + '423': + description: This session is unavailable; contact support. + 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: + - agent_harness_session: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..b91592b5d --- /dev/null +++ b/specification/resources/agents/agents_create_session_input.yml @@ -0,0 +1,79 @@ +operationId: harness_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: +- 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 +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 + '423': + description: This session is unavailable; contact support. + 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: + - agent_harness_session:operate 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..4478c92fc --- /dev/null +++ b/specification/resources/agents/agents_create_session_workspace_part_upload_urls.yml @@ -0,0 +1,98 @@ +operationId: harness_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: +- 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: 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 + '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_create_session_workspace_part_upload_urls.yml +security: +- bearer_auth: + - agent_harness_session:operate 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..39713d0d8 --- /dev/null +++ b/specification/resources/agents/agents_create_session_workspace_transfer.yml @@ -0,0 +1,154 @@ +operationId: harness_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: +- 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 +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 + '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_create_session_workspace_transfer.yml +security: +- bearer_auth: + - agent_harness_session:operate 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..057d7c900 --- /dev/null +++ b/specification/resources/agents/agents_create_session_workspace_upload.yml @@ -0,0 +1,138 @@ +operationId: harness_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: +- 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: 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 + '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_create_session_workspace_upload.yml +security: +- bearer_auth: + - agent_harness_session:operate diff --git a/specification/resources/agents/agents_create_template.yml b/specification/resources/agents/agents_create_template.yml new file mode 100644 index 000000000..2a9aa27e2 --- /dev/null +++ b/specification/resources/agents/agents_create_template.yml @@ -0,0 +1,46 @@ +operationId: harness_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: +- Harness Runtime +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: + - agent_harness_session:manage diff --git a/specification/resources/agents/agents_delete_config.yml b/specification/resources/agents/agents_delete_config.yml new file mode 100644 index 000000000..7a463f652 --- /dev/null +++ b/specification/resources/agents/agents_delete_config.yml @@ -0,0 +1,67 @@ +operationId: harness_delete_config +summary: Soft-delete an Environment 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: +- Harness Runtime +parameters: +- in: path + name: config_id + required: true + description: The Environment 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 + '409': + description: Config still has active sessions (or active credential binding sets). + 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 + '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: + - agent_harness_session:manage diff --git a/specification/resources/agents/agents_delete_session.yml b/specification/resources/agents/agents_delete_session.yml new file mode 100644 index 000000000..f6d80f28a --- /dev/null +++ b/specification/resources/agents/agents_delete_session.yml @@ -0,0 +1,74 @@ +operationId: harness_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: +- 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: 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 + '423': + description: This session is unavailable; contact support. + 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 + '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: + - agent_harness_session:manage 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..4b432bd39 --- /dev/null +++ b/specification/resources/agents/agents_delete_session_checkpoint.yml @@ -0,0 +1,65 @@ +operationId: harness_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: +- 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: 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 + '423': + description: This session is unavailable; contact support. + 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_delete_session_checkpoint.yml +security: +- bearer_auth: + - agent_harness_session:operate diff --git a/specification/resources/agents/agents_delete_template.yml b/specification/resources/agents/agents_delete_template.yml new file mode 100644 index 000000000..8175e5829 --- /dev/null +++ b/specification/resources/agents/agents_delete_template.yml @@ -0,0 +1,44 @@ +operationId: harness_delete_template +summary: DeleteTemplate deletes a team custom template. +description: Global templates cannot be deleted via this API. +tags: +- Harness Runtime +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: + - agent_harness_session:manage diff --git a/specification/resources/agents/agents_get_config.yml b/specification/resources/agents/agents_get_config.yml new file mode 100644 index 000000000..c6354816b --- /dev/null +++ b/specification/resources/agents/agents_get_config.yml @@ -0,0 +1,52 @@ +operationId: harness_get_config +summary: Get an active Environment Config and its environment spec. +description: Returns one team-scoped Environment Config including the sanitized environment spec and redacted credential + slot metadata. Secret values are never returned. +tags: +- Harness Runtime +parameters: +- in: path + name: config_id + required: true + description: The Environment 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: + - agent_harness_session: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..93378f40f --- /dev/null +++ b/specification/resources/agents/agents_get_session.yml @@ -0,0 +1,57 @@ +operationId: harness_get_session +summary: GetSession returns the current snapshot of a session. +description: GetSession returns the current snapshot of a session. +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 +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 + '423': + description: This session is unavailable; contact support. + 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_get_session.yml +security: +- bearer_auth: + - agent_harness_session: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..e506c4cb8 --- /dev/null +++ b/specification/resources/agents/agents_get_session_checkpoint.yml @@ -0,0 +1,65 @@ +operationId: harness_get_session_checkpoint +summary: GetCheckpoint returns the current snapshot of a checkpoint. +description: GetCheckpoint returns the current snapshot of a checkpoint. +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: 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 + '423': + description: This session is unavailable; contact support. + 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_get_session_checkpoint.yml +security: +- bearer_auth: + - agent_harness_session: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..d57f9c321 --- /dev/null +++ b/specification/resources/agents/agents_get_session_workspace_download.yml @@ -0,0 +1,135 @@ +operationId: harness_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: `` + `