dots.v2.agents.sessions.bySession_id().patch()

Generated on 5 Nov 2026 from DoTs version v1.23.0

Usage

client.v2.agents.sessions.bySession_id(session_id).patch(body: Patch_session_request, requestConfiguration?: RequestConfiguration<object>): Promise<undefined | Get_session_response>

Description

Partial update of session-scoped settings (not the agent manifest / config). The body must include at least one recognized patchable property; an empty object {} is 400. Only properties listed on PatchSessionRequest are accepted, any other top-level JSON key is rejected with 400. Omitted properties are left unchanged. Today the only patchable field is resume_on_topoff; more session settings may be added over time. Terminal sessions (DESTROYED, FAILED) cannot be patched.

Parameters

Path Parameters

session_id string required

Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890

The session UUID.

Request Body

resumeOnTopoff boolean optional

Example: false

When present, sets whether this session opts in to automatic resumption when the team's prepayment balance is restored after a low-balance pause. Session-scoped consent, not config-scoped. Omitted properties are not modified.

Request Sample

Show Request Sample
import { FetchRequestAdapter } from "@microsoft/kiota-http-fetchlibrary";
import {
    createDigitalOceanClient,
    DigitalOceanApiKeyAuthenticationProvider,
} from "@digitalocean/dots";

const authProvider = new DigitalOceanApiKeyAuthenticationProvider(process.env.DIGITALOCEAN_TOKEN!);
const adapter = new FetchRequestAdapter(authProvider);
const client = createDigitalOceanClient(adapter);

const response = await client.v2.agents.sessions
    .bySession_id("a1b2c3d4-e5f6-7890-abcd-ef1234567890").patch({
    resumeOnTopoff: false,
});

Response Example

Show Response Example
{
  "session": {
    "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "demo-agent",
    "parent_session_id": "example",
    "fork_id": "11111111-2222-3333-4444-555555555555",
    "fork_from_checkpoint_id": "example",
    "agent_kind": "AGENT_KIND_UNSPECIFIED",
    "status": "SESSION_STATUS_UNSPECIFIED",
    "sandbox_id": "example",
    "created_at": "2026-08-01T12:00:00Z",
    "last_event_at": "2026-08-01T12:00:00Z",
    "keep_warm": false,
    "resume_on_topoff": false,
    "pause_reason": "example",
    "idle_timeout_seconds": 60,
    "repo_hint": "example",
    "warnings": [],
    "config_id": "11111111-2222-3333-4444-555555555555",
    "openai_session_id": "example",
    "openai_environment_id": "example",
    "region": "ric1",
    "workspace_id": "019a2f4e-8c1d-7b3a-9e5f-2d6c8a1b4e70"
  }
}

More Information

See /v2/agents/sessions/{session_id} in the API reference for additional detail on responses, headers, parameters, and more.

We can't find any results for your search.

Try using different keywords or simplifying your search terms.