# StartSandbox starts a stopped sandbox; a backend that preserved memory resumes it. [API catalog](/reference/api/) · [Docker Sandboxes overview](/reference/api/sandboxes/latest/) · [Product manual](https://docs.docker.com/ai/sandboxes-api/) · [OpenAPI specification](/reference/api/sandboxes/api.yaml) API version: v1 > This API is experimental. Features, interfaces, > and behavior may change. `POST /v1/sandboxes/{sandbox}/start` StartSandbox starts a stopped sandbox; a backend that preserved memory resumes it. Action: a lifecycle transition is not a representation a caller can PUT. ## Connection and access [API connection and authentication guidance](/reference/api/sandboxes/latest/#authentication) Server: `https://connect.docker.com/sandboxes` Effective security: alternatives are OR; schemes within an alternative are AND. An empty array declares no HTTP authentication requirement. ```json [ { "bearer": [] } ] ``` ## Example request Replace placeholders and provide the required credentials or request body. ```console curl \ --request POST \ --header 'If-Match: ' \ --header "Authorization: Bearer ${TOKEN}" \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data-binary @request-body \ 'https://connect.docker.com/sandboxes/v1/sandboxes//start' ``` Prepare request-body using the selected media type and schema. ## Parameters ### sandbox Location: path. Required: yes. The sandbox id. ```json { "description": "The sandbox id.", "in": "path", "name": "sandbox", "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1start/post/parameters/0", "required": true, "schema": { "type": "string" } } ``` ### Idempotency-Key Location: header. Required: no. Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours. ```json { "description": "Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours.", "in": "header", "name": "Idempotency-Key", "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1start/post/parameters/1", "schema": { "description": "Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours.", "title": "Idempotency-Key", "type": "string" } } ``` ### If-Match Location: header. Required: yes. The complete quoted strong entity-tag observed on the resource, including its quotes. Every mutation of an existing resource requires it: an absent value answers 428 and a stale one 412, each carrying failedPrecondition in the body. ```json { "description": "The complete quoted strong entity-tag observed on the resource, including its quotes. Every mutation of an existing resource requires it: an absent value answers 428 and a stale one 412, each carrying failedPrecondition in the body.", "in": "header", "name": "If-Match", "pointer": "/paths/~1v1~1sandboxes~1{sandbox}~1start/post/parameters/2", "required": true, "schema": { "description": "etag is the required precondition, the value the target's last read returned.\nAn absent one refuses etag_required and a stale one etag_mismatch.", "title": "If-Match", "type": "string" } } ``` ## Request and responses ### Request application/json Schema: ```json { "additionalProperties": false, "description": "StartSandboxRequest starts or resumes a sandbox.", "properties": {}, "title": "StartSandboxRequest", "type": "object" } ``` ### Response 200 application/json Success Schema: ```json { "allOf": [ { "$ref": "#/components/schemas/Sandbox" }, { "not": { "properties": { "core": { "properties": { "status": { "enum": [ "starting" ] } }, "required": [ "status" ] } }, "required": [ "core" ] } } ] } ``` Headers: ```json { "ETag": { "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", "schema": { "type": "string" } } } ``` ### Response 202 application/json Accepted. The resource is still progressing; read it or follow its events until completion. Schema: ```json { "allOf": [ { "$ref": "#/components/schemas/Sandbox" }, { "properties": { "core": { "properties": { "status": { "enum": [ "starting" ] } }, "required": [ "status" ] } }, "required": [ "core" ] } ] } ``` Headers: ```json { "ETag": { "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", "schema": { "type": "string" } } } ``` ### Response 409 application/json The Idempotency-Key was already used with a different payload. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` failedPrecondition: ```json { "code": "failedPrecondition", "message": "The Idempotency-Key was already used with a different payload." } ``` ### Response 412 application/json The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` etag_mismatch: ```json { "code": "failedPrecondition", "details": [ { "@type": "type.googleapis.com/docker.sandboxes.v1.EtagMismatch", "currentEtag": "v2" } ], "message": "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." } ``` ### Response 428 application/json No precondition was sent. The body carries failedPrecondition naming etag_required. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` etag_required: ```json { "code": "failedPrecondition", "message": "etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required." } ``` ### Response default application/json The structured Error body identifies the failure with a stable code and optional typed details. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` Schema example: ```json { "code": "notFound", "details": [], "message": "sandbox not found" } ``` ## Complete operation contract ```json { "description": "StartSandbox starts a stopped sandbox; a backend that preserved memory resumes it.\nAction: a lifecycle transition is not a representation a caller can PUT.", "operationId": "startSandbox", "parameters": [ { "description": "The sandbox id.", "in": "path", "name": "sandbox", "required": true, "schema": { "type": "string" } }, { "description": "Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours.", "in": "header", "name": "Idempotency-Key", "schema": { "description": "Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours.", "title": "Idempotency-Key", "type": "string" } }, { "description": "The complete quoted strong entity-tag observed on the resource, including its quotes. Every mutation of an existing resource requires it: an absent value answers 428 and a stale one 412, each carrying failedPrecondition in the body.", "in": "header", "name": "If-Match", "required": true, "schema": { "description": "etag is the required precondition, the value the target's last read returned.\nAn absent one refuses etag_required and a stale one etag_mismatch.", "title": "If-Match", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "StartSandboxRequest starts or resumes a sandbox.", "properties": {}, "title": "StartSandboxRequest", "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Sandbox" }, { "not": { "properties": { "core": { "properties": { "status": { "enum": [ "starting" ] } }, "required": [ "status" ] } }, "required": [ "core" ] } } ] } } }, "description": "Success", "headers": { "ETag": { "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", "schema": { "type": "string" } } } }, "202": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Sandbox" }, { "properties": { "core": { "properties": { "status": { "enum": [ "starting" ] } }, "required": [ "status" ] } }, "required": [ "core" ] } ] } } }, "description": "Accepted. The resource is still progressing; read it or follow its events until completion.", "headers": { "ETag": { "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "examples": { "failedPrecondition": { "summary": "The Idempotency-Key was already used with a different payload.", "value": { "code": "failedPrecondition", "message": "The Idempotency-Key was already used with a different payload." } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The Idempotency-Key was already used with a different payload." }, "412": { "content": { "application/json": { "examples": { "etag_mismatch": { "summary": "The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value.", "value": { "code": "failedPrecondition", "details": [ { "@type": "type.googleapis.com/docker.sandboxes.v1.EtagMismatch", "currentEtag": "v2" } ], "message": "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." }, "428": { "content": { "application/json": { "examples": { "etag_required": { "summary": "No precondition was sent. The body carries failedPrecondition naming etag_required.", "value": { "code": "failedPrecondition", "message": "etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required." } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No precondition was sent. The body carries failedPrecondition naming etag_required." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The structured Error body identifies the failure with a stable code and optional typed details." } }, "security": [ { "bearer": [] } ], "summary": "StartSandbox starts a stopped sandbox; a backend that preserved memory resumes it.", "tags": [ "Sandboxes" ], "x-sbx-authenticated-only": false, "x-sbx-conditional-permissions": [], "x-sbx-error-responses": [ { "code": "FAILED_PRECONDITION", "description": "The Idempotency-Key was already used with a different payload." } ], "x-sbx-plane": "control", "x-sbx-required-permissions": [ "sandboxesLifecycle" ], "x-sbx-resource-response": { "$ref": "#/components/schemas/Sandbox" }, "x-sbx-serving-surface": "management" } ``` ## Referenced schemas - [#/components/schemas/Error](/reference/api/sandboxes/latest/schemas/Error/) - [#/components/schemas/Sandbox](/reference/api/sandboxes/latest/schemas/Sandbox/)