docker/docs
1
0
Fork 0
mirror of https://github.com/docker/docs.git synced 2026-10-23 18:09:02 +03:00
Code Activity
Files
4cedf2e052d4a0b83a9bb469541bfb7ccc225a72
docs/layouts/api-docs.markdown.md
David Karlsson bed22bda81 docs: Cloud Sandboxes API and SDK (#26168) 
## Description

Add an experimental Sandboxes API and SDK section alongside Docker
Sandboxes under AI and agents, at `/ai/sandboxes-api/`. Cover
installation of `@docker/sandboxes`, browser and PAT authentication, and
a TypeScript walkthrough that launches the shell kit, runs a command,
and deletes the sandbox. Explain kits and image choices with examples,
along with compute sizes, quotas, permissions, resource lifecycle,
errors, and retries. Link subscription setup and billing to the shared
Docker Agentic Platform guide. Preserve the previous
`/ai/sandboxes/api/` URLs with redirects.

Uses the shared Docker Agentic Platform documentation merged in #26142.
Sibling to #26158, which introduces CLI-side Cloud Sandboxes
documentation.

Include 36 SDK cookbook recipes at `/ai/sandboxes-api/cookbook/` and the
public REST API reference at `/reference/api/sandboxes/`. Import the
generated export from `docker/sbx-api` commit `60d79c1d` (source
`1a7f4026`). Overview and installation remain maintained here. The
reference uses the shared API renderer from main, with separate
operation and schema pages, streaming and WebSocket details, and a
downloadable OpenAPI spec. An API reference link appears in the API/SDK
sidebar. A pinned manifest and import script provide the basis for later
release automation.

Examples are optional in the shared renderer; supplied examples still
have to pass schema validation. Requests without body examples use a
request-body file with instructions to prepare it. The import copies all
selected recipes and the OpenAPI specification byte for byte from the
corrected upstream export, without patches or link rewrites. The broken
naming recipe remains temporarily excluded.

This remains a draft pending validation against the published npm SDK.
The imported cookbook contains the TypeScript-only guidance, five-minute
request deadlines, kit-readiness explanation, active-policy status
requirement, and snapshot-deletion and lifetime-renewal restrictions.

Validation: scoped Markdown and Vale checks, full Hugo build, rendered
navigation, redirects, and internal links, and TypeScript type-checking
against the generated public SDK from `docker/sbx-api` commit
`68f214b9`. Import validation also covers all 60 REST operations and 188
schema definitions, 1,198 imported-page links and anchors,
desktop/mobile rendering, Markdown output, spec delivery, and a repeat
import. The shared renderer tests, strict generation for all five APIs
(zero diagnostics), full Hugo build, and verification of 453
HTML/Markdown page pairs and API links pass. No live sandbox execution.
The corrected export passes strict generation for all five APIs with
zero diagnostics, scoped Markdown/Vale lint, a full Hugo build, and
verification of 453 HTML/Markdown page pairs and API links. A repeat
import produces identical files. The spec update changes examples only;
schemas and operations are unchanged.

@netlify /ai/sandboxes-api/

Generated by Codex

---------

Co-authored-by: Claude <noreply@anthropic.com>
2026-09-24 18:06:30 +02:00

4.8 KiB
Raw Blame History

{{- $data := index hugo.Data "api-reference" -}} {{- $api := dict -}}{{- range data.apis -}}{{- if eq .id .Params.apiID -}}{{- $api = . -}}{{- end -}}{{- end -}}

{{ .Title }}

{{ if eq .Params.view "catalog" }} Choose a Docker HTTP API: {{ range $data.apis }}

  • [{{ .title }} API {{ .version }}]({{ .url }}): {{ len .operations }} operations; {{ .connection }} connection {{ end }} {{ range $data.legacyAPIs }}
  • [{{ .title }}]({{ .url }}): {{ .description }} {{ end }} {{ else }} API catalog · [{{ $api.title }} overview]({{ $api.url }}) · [Product manual]({{ ref . $api.manual }}) · [OpenAPI specification]({{ $api.sourceURL }})

API version: {{ $api.version }}

{{ if $api.experimental }}

This API is experimental. Features, interfaces, and behavior may change. {{ end }}

{{ if eq .Params.view "overview" }}

Overview

{{ partial "api-reference/description.html" (dict "text" $api.description "api" $api) }}

{{ if eq $api.connection "unix" }}Connecting to {{ $api.title }}{{ else }}Connecting to the {{ $api.title }} API{{ end }}

{{ range $name, $scheme := $api.securitySchemes }}{{ with $scheme.description }}

{{ index $scheme "x-displayName" | default $name }}

{{ . }} {{ end }}{{ end }} {{ range $api.servers }} Server: {{ .url }} {{ range $name,$variable := .variables }} {{ $name }}: {{ $variable.description }} {{ end }}{{ end }} {{ if eq $api.connection "unix" }}

curl --unix-socket /var/run/docker.sock http://localhost/v{{ $api.version }}/version

{{ end }} {{ range $api.guides }} {{ $guide := site.GetPage (index (split . "#") 0) }}

  • [{{ guide.Title }}]({{ ref . }}) {{ end }}

{{ range (partial "api-reference/overview-tags.html" $api) }}

{{ .summary }}

{{ partial "api-reference/description.html" (dict "text" .description "api" $api) }} {{ end }}

Operations

{{ range $api.operations }}

  • [{{ .method }} {{ .path }}]({{ .url }}): {{ .summary }} {{ end }}

Schemas

{{ range $api.schemas }}

  • [{{ .name }}]({{ .url }}) {{ end }} {{ else if eq .Params.view "operation" }} {{ range api.operations }}{{ if eq .id .Params.operationID }} {{ .method }} {{ .path }}

{{ partial "api-reference/description.html" (dict "text" .description "api" $api) }} {{ if .deprecated }} Deprecated operation. {{ end }}

Connection and access

[API connection and authentication guidance]({{ $api.url }}#authentication) {{ if and (eq $api.product "engine") (where .parameters "name" "X-Registry-Auth") }} X-Registry-Auth delegates registry credentials and does not authenticate the daemon caller. {{ end }} {{ range .servers }} Server: {{ .url }} {{ range $name,$variable := .variables }} {{ $name }}: {{ $variable.description }} {{ end }}{{ end }} Effective security: alternatives are OR; schemes within an alternative are AND. An empty array declares no HTTP authentication requirement.

{{ .security | jsonify (dict "indent" "  ") }}

{{ if .curl }}

Example request

Replace placeholders and provide the required credentials or request body.

{{ .curl }}

{{ end }} {{ range .curlNotes }} {{ . }} {{ end }} {{ with index .raw "x-websocket" }}

WebSocket session

Subprotocol: {{ .subprotocol }}

{{ .authentication }}

{{ .browser }}

{{ .reconnect }}

{{ .terminalFrame }}

{{ . | jsonify (dict "indent" "  ") }}

{{ end }}

Parameters

{{ range .parameters }}

{{ .name }}

Location: {{ .in }}. Required: {{ if .required }}yes{{ else }}no{{ end }}.

{{ partial "api-reference/description.html" (dict "text" .description "api" $api) }}

{{ . | jsonify (dict "indent" "  ") }}

{{ end }}

Request and responses

{{ range .variants }}

{{ .direction }} {{ .status }} {{ .media }}

{{ partial "api-reference/description.html" (dict "text" .description "api" $api) }} {{ if not .media }} No response content is declared. {{ end }} {{ if isset . "schema" }} Schema:

{{ .schema | jsonify (dict "indent" "  ") }}

{{ end }} {{ if isset . "itemSchema" }} Stream item schema:

{{ .itemSchema | jsonify (dict "indent" "  ") }}

{{ end }} {{ with .headers }} Headers:

{{ . | jsonify (dict "indent" "  ") }}

{{ end }} {{ $variant := . }} {{ range $key := slice "encoding" "itemEncoding" "prefixEncoding" }} {{ with index $variant $key }} {{ $key }}:

{{ . | jsonify (dict "indent" "  ") }}

{{ end }}{{ end }} {{ range .examples }} {{ .name }}:

{{ .text }}

{{ end }} {{ end }}

Complete operation contract

{{ .raw | jsonify (dict "indent" "  ") }}

Referenced schemas

{{ range .references }}

  • {{ if .url }}[{{ .ref }}]({{ .url }}){{ else }}{{ .ref }}{{ end }} {{ end }} {{ end }}{{ end }} {{ else if eq .Params.view "schema" }} {{ range api.schemas }}{{ if eq .name .Params.schemaName }} Schema constraints and annotations:
{{ .schema | jsonify (dict "indent" "  ") }}

{{ end }}{{ end }} {{ end }} {{ end }}

View Git Blame Copy Permalink