From 0058aca7411d6ed8c437db59bdbefa1bb207e4c5 Mon Sep 17 00:00:00 2001 From: Sean Roberts Date: Thu, 22 Oct 2026 13:40:27 -0700 Subject: [PATCH] docs: describe how to follow up on 202 Accepted responses Each 202 now says what the response contains (no body for any of them), what has already happened by the time it returns, and which operation and `state` value to poll to confirm completion. purgeCache states plainly that there is nothing to poll. Descriptions only, matching current API behavior; the regenerated Go client changes in doc comments only. Co-Authored-By: Claude Opus 5.5 (1M context) --- .../archive_agent_runner_responses.go | 2 +- .../delete_agent_runner_responses.go | 2 +- .../delete_agent_runner_session_responses.go | 2 +- .../delete_site_dev_servers_responses.go | 2 +- .../operations/purge_cache_responses.go | 2 +- .../operations/stop_agent_runner_responses.go | 2 +- .../stop_agent_runner_session_responses.go | 2 +- swagger.yml | 45 ++++++++++++++++--- 8 files changed, 45 insertions(+), 14 deletions(-) diff --git a/go/plumbing/operations/archive_agent_runner_responses.go b/go/plumbing/operations/archive_agent_runner_responses.go index fae96947..028b8c23 100644 --- a/go/plumbing/operations/archive_agent_runner_responses.go +++ b/go/plumbing/operations/archive_agent_runner_responses.go @@ -61,7 +61,7 @@ func NewArchiveAgentRunnerAccepted() *ArchiveAgentRunnerAccepted { /* ArchiveAgentRunnerAccepted handles this case with default header values. -Accepted +Accepted. The response has no body. The archive is applied before this returns: `getAgentRunner` (`GET /agent_runners/{agent_runner_id}`) reports `state` as `archived`. */ type ArchiveAgentRunnerAccepted struct { } diff --git a/go/plumbing/operations/delete_agent_runner_responses.go b/go/plumbing/operations/delete_agent_runner_responses.go index 8db6e4d1..47f7c588 100644 --- a/go/plumbing/operations/delete_agent_runner_responses.go +++ b/go/plumbing/operations/delete_agent_runner_responses.go @@ -49,7 +49,7 @@ func NewDeleteAgentRunnerAccepted() *DeleteAgentRunnerAccepted { /* DeleteAgentRunnerAccepted handles this case with default header values. -Accepted +Accepted. Same behavior as `stopAgentRunner`: the response has no body, the run's active sessions are set to `cancelled` before it returns, and the sandbox shuts down in the background. To confirm, poll `getAgentRunnerSession` (`GET /agent_runners/{agent_runner_id}/sessions/{agent_runner_session_id}`) and check that `state` is `cancelled`. */ type DeleteAgentRunnerAccepted struct { } diff --git a/go/plumbing/operations/delete_agent_runner_session_responses.go b/go/plumbing/operations/delete_agent_runner_session_responses.go index 375f3072..22234984 100644 --- a/go/plumbing/operations/delete_agent_runner_session_responses.go +++ b/go/plumbing/operations/delete_agent_runner_session_responses.go @@ -49,7 +49,7 @@ func NewDeleteAgentRunnerSessionAccepted() *DeleteAgentRunnerSessionAccepted { /* DeleteAgentRunnerSessionAccepted handles this case with default header values. -Accepted +Accepted. Same behavior as `stopAgentRunnerSession`: the response has no body, the session is set to `cancelled` before it returns, and the sandbox shuts down in the background. To confirm, poll `getAgentRunnerSession` (`GET /agent_runners/{agent_runner_id}/sessions/{agent_runner_session_id}`) and check that `state` is `cancelled`. */ type DeleteAgentRunnerSessionAccepted struct { } diff --git a/go/plumbing/operations/delete_site_dev_servers_responses.go b/go/plumbing/operations/delete_site_dev_servers_responses.go index 6e3fdfac..98dfab61 100644 --- a/go/plumbing/operations/delete_site_dev_servers_responses.go +++ b/go/plumbing/operations/delete_site_dev_servers_responses.go @@ -49,7 +49,7 @@ func NewDeleteSiteDevServersAccepted() *DeleteSiteDevServersAccepted { /* DeleteSiteDevServersAccepted handles this case with default header values. -OK +Accepted. The response has no body. The branch's active dev servers are set to `stopping` before this returns and shut down in the background. Poll `getSiteDevServer` (`GET /sites/{site_id}/dev_servers/{dev_server_id}`) or `listSiteDevServers` (`GET /sites/{site_id}/dev_servers`) until `state` is `done` (or `error`). */ type DeleteSiteDevServersAccepted struct { } diff --git a/go/plumbing/operations/purge_cache_responses.go b/go/plumbing/operations/purge_cache_responses.go index b3b1ebf5..c5439665 100644 --- a/go/plumbing/operations/purge_cache_responses.go +++ b/go/plumbing/operations/purge_cache_responses.go @@ -52,7 +52,7 @@ func NewPurgeCacheAccepted() *PurgeCacheAccepted { /* PurgeCacheAccepted handles this case with default header values. -OK +Accepted. The purge is queued and propagates across the CDN asynchronously. The response has no body and there is no status resource to poll for completion. */ type PurgeCacheAccepted struct { } diff --git a/go/plumbing/operations/stop_agent_runner_responses.go b/go/plumbing/operations/stop_agent_runner_responses.go index 7693987c..3caf12d9 100644 --- a/go/plumbing/operations/stop_agent_runner_responses.go +++ b/go/plumbing/operations/stop_agent_runner_responses.go @@ -49,7 +49,7 @@ func NewStopAgentRunnerAccepted() *StopAgentRunnerAccepted { /* StopAgentRunnerAccepted handles this case with default header values. -Accepted +Accepted. The response has no body. The run's active sessions are set to `cancelled` before this returns, and the sandbox shuts down in the background. To confirm, poll `getAgentRunnerSession` (`GET /agent_runners/{agent_runner_id}/sessions/{agent_runner_session_id}`) and check that `state` is `cancelled`. */ type StopAgentRunnerAccepted struct { } diff --git a/go/plumbing/operations/stop_agent_runner_session_responses.go b/go/plumbing/operations/stop_agent_runner_session_responses.go index 1ec42279..ea9c6e0d 100644 --- a/go/plumbing/operations/stop_agent_runner_session_responses.go +++ b/go/plumbing/operations/stop_agent_runner_session_responses.go @@ -49,7 +49,7 @@ func NewStopAgentRunnerSessionAccepted() *StopAgentRunnerSessionAccepted { /* StopAgentRunnerSessionAccepted handles this case with default header values. -Accepted +Accepted. The response has no body. The session is set to `cancelled` before this returns, and the sandbox shuts down in the background. To confirm, poll `getAgentRunnerSession` (`GET /agent_runners/{agent_runner_id}/sessions/{agent_runner_session_id}`) and check that `state` is `cancelled`. */ type StopAgentRunnerSessionAccepted struct { } diff --git a/swagger.yml b/swagger.yml index cd6d3a32..c64bb0a7 100644 --- a/swagger.yml +++ b/swagger.yml @@ -843,7 +843,10 @@ paths: required: true responses: '202': - description: OK + description: >- + Accepted. The purge is queued and propagates across the CDN asynchronously. + The response has no body and there is no status resource to poll for + completion. '400': description: Invalid request parameters '404': @@ -2510,7 +2513,12 @@ paths: description: Same as `POST /agent_runners/{agent_runner_id}/stop`. Doesn't delete the run. responses: '202': - description: Accepted + description: >- + Accepted. Same behavior as `stopAgentRunner`: the response has no body, the + run's active sessions are set to `cancelled` before it returns, and the + sandbox shuts down in the background. To confirm, poll `getAgentRunnerSession` + (`GET /agent_runners/{agent_runner_id}/sessions/{agent_runner_session_id}`) and check + that `state` is `cancelled`. default: $ref: '#/responses/error' /agent_runners/{agent_runner_id}/stop: @@ -2525,7 +2533,12 @@ paths: description: Stops the run's active session. Stopping happens in the background. responses: '202': - description: Accepted + description: >- + Accepted. The response has no body. The run's active sessions are set to + `cancelled` before this returns, and the sandbox shuts down in the + background. To confirm, poll `getAgentRunnerSession` + (`GET /agent_runners/{agent_runner_id}/sessions/{agent_runner_session_id}`) and check + that `state` is `cancelled`. default: $ref: '#/responses/error' /agent_runners/{agent_runner_id}/diff: @@ -2569,7 +2582,10 @@ paths: tags: [agentRunner] responses: '202': - description: Accepted + description: >- + Accepted. The response has no body. The archive is applied before this + returns: `getAgentRunner` (`GET /agent_runners/{agent_runner_id}`) reports + `state` as `archived`. '404': description: Not Found '422': @@ -2764,7 +2780,12 @@ paths: description: Same as `POST /agent_runners/{agent_runner_id}/sessions/{agent_runner_session_id}/stop`. Doesn't delete the session. responses: '202': - description: Accepted + description: >- + Accepted. Same behavior as `stopAgentRunnerSession`: the response has no + body, the session is set to `cancelled` before it returns, and the sandbox + shuts down in the background. To confirm, poll `getAgentRunnerSession` + (`GET /agent_runners/{agent_runner_id}/sessions/{agent_runner_session_id}`) and check + that `state` is `cancelled`. default: $ref: '#/responses/error' /agent_runners/{agent_runner_id}/sessions/{agent_runner_session_id}/stop: @@ -2783,7 +2804,12 @@ paths: description: Stops the session. Stopping happens in the background. responses: '202': - description: Accepted + description: >- + Accepted. The response has no body. The session is set to `cancelled` + before this returns, and the sandbox shuts down in the background. + To confirm, poll `getAgentRunnerSession` + (`GET /agent_runners/{agent_runner_id}/sessions/{agent_runner_session_id}`) and check + that `state` is `cancelled`. default: $ref: '#/responses/error' /agent_runners/{agent_runner_id}/sessions/{agent_runner_session_id}/answers: @@ -3353,7 +3379,12 @@ paths: in: query responses: '202': - description: OK + description: >- + Accepted. The response has no body. The branch's active dev servers are set + to `stopping` before this returns and shut down in the background. Poll + `getSiteDevServer` (`GET /sites/{site_id}/dev_servers/{dev_server_id}`) or + `listSiteDevServers` (`GET /sites/{site_id}/dev_servers`) until `state` is + `done` (or `error`). default: $ref: '#/responses/error' # end sites/{site_id}/dev_servers