dots.v2.agents.sessions.post()

Generated on 13 Nov 2026 from DoTs version v1.24.0

Usage

client.v2.agents.sessions.post(body: Create_session_config_request, requestConfiguration?: RequestConfiguration<SessionsRequestBuilderPostQueryParameters>): Promise<undefined | Definitions_create_session_response>

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.

Parameters

Query Parameters

openaiSessionId string optional

Example: sess_abc123

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.

resumeOnTopoff boolean optional

Example: false

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.

Headers

X-Device-UUID string optional

Example: device-uuid-example

Optional hardware device id forwarded by doctl. Persisted on the session row for lifecycle attribution. Values over 128 bytes are ignored.

Request Body

name string required

Example: demo-agent

Session name, independent of the config name. Must satisfy the existing environment-spec metadata.name rules and must not be UUID-shaped.

Min length: 1

Max length: 64

configId string required

Example: 11111111-2222-3333-4444-555555555555

resumeOnTopoff boolean optional

Example: false

Opt the new session in to automatic resumption when the team's prepayment balance is restored. Defaults to false. Session-scoped, not config-scoped: the referenced config never confers this, so one shared config cannot enrol every session created from it. Omit to leave the default (or to let the ?resume_on_topoff= query parameter supply it).

region string optional

Example: ric1

Optional placement check, not a placement choice: the session is always created in the region whose API host served the request. If set, it must equal that region, or the request fails with 400 and a region_mismatch message. Honored only for teams on the regional routing rollout; ignored otherwise.

workspaceId string optional

Example: 019a2f4e-8c1d-7b3a-9e5f-2d6c8a1b4e70

Optional persistent workspace to attach at create; its files are mounted at /workspace. The workspace must be AVAILABLE, otherwise the request returns 409. Accepted only in this JSON form; an environment spec that contains workspace_id is rejected with 400. Returns 403 when persistent workspaces are not enabled for the team.

Max length: 255

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.post({
    name: "demo-agent",
    configId: "11111111-2222-3333-4444-555555555555",
    resumeOnTopoff: false,
    region: "ric1",
    workspaceId: "019a2f4e-8c1d-7b3a-9e5f-2d6c8a1b4e70",
});

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 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.