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 legacyagents.digitalocean.com/v1alpha1envelope (deprecated). A top-levelapiVersionkey 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
openaiSessionIdstring optionalExample:
sess_abc123OpenAI 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.
resumeOnTopoffboolean optionalExample:
falseOpt 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-UUIDstring optionalExample:
device-uuid-exampleOptional hardware device id forwarded by doctl. Persisted on the session row for lifecycle attribution. Values over 128 bytes are ignored.
Request Body
namestring requiredExample:
demo-agentSession name, independent of the config name. Must satisfy the existing environment-spec metadata.name rules and must not be UUID-shaped.
configIdstring requiredExample:
11111111-2222-3333-4444-555555555555resumeOnTopoffboolean optionalExample:
falseOpt 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).
regionstring optionalExample:
ric1Optional 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.
workspaceIdstring optionalExample:
019a2f4e-8c1d-7b3a-9e5f-2d6c8a1b4e70Optional persistent workspace to attach at create; its files are mounted at
/workspace. The workspace must beAVAILABLE, 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.
Request Sample
Response Example
More Information
See /v2/agents/sessions in the API reference for additional detail on responses, headers, parameters, and more.