Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/opensandbox-group/OpenSandbox/llms.txt

Use this file to discover all available pages before exploring further.

The Diagnostics API provides best-effort plain-text diagnostic snapshots for a sandbox. It is intended for human operators and troubleshooting agents who need to collect runtime diagnostic material without depending on a stable structured observability model. Endpoints return a JSON descriptor whose payload is either embedded inline as content or made available through a short-lived contentUrl for larger payloads. The diagnostic content itself is text/plain display-oriented text — do not parse individual lines as a stable schema, as the format may change across server versions.
This API is not an audit log API and does not define the canonical observability schema for OpenSandbox. It does not provide streaming, pagination, or long-term retention guarantees. Structured telemetry and long-term storage are provided separately.
Both endpoints share the base URL http://localhost:8080/v1 and require the OPEN-SANDBOX-API-KEY header.

​
GET /v1/sandboxes//diagnostics/logs

Retrieves a best-effort descriptor for sandbox diagnostic log text. Depending on the selected scope and server configuration, log text may include sandbox container stdout/stderr, lifecycle diagnostic text, network diagnostic text, or other implementation-defined diagnostic material. Auth: OPEN-SANDBOX-API-KEY header required.

​
Path Parameters

​
sandboxId
string
required
Unique sandbox identifier.

​
Query Parameters

​
scope
string
required
Diagnostic scope selector. Known values include container, lifecycle, runtime, network, process, and all. Supported scopes are implementation-defined and may vary by deployment. Pass all for a best-effort aggregate across supported scopes.

​
Response — 200 OK

​
sandboxId
string
required
Unique sandbox identifier echoed from the request.
​
kind
string
required
Diagnostic payload kind. Value: logs.
​
scope
string
required
Diagnostic scope used for this response.
​
delivery
string
required
How the diagnostic text payload is delivered. Enum: inline, url.
​
contentType
string
required
Media type of the diagnostic payload. Example: "text/plain; charset=utf-8".
​
content
string
Inline diagnostic text payload. Present only when delivery is inline.
​
contentUrl
string
URL where the diagnostic text can be downloaded. Present only when delivery is url.
​
contentLength
integer
Payload size in bytes, when known.
​
expiresAt
string
Expiration time for the download URL (RFC 3339). Present when delivery is url.
​
truncated
boolean
required
Whether the diagnostic payload was intentionally truncated by the server due to size limits.
​
warnings
array
Non-fatal warnings about payload completeness or availability (e.g. expired Kubernetes Events).

​
Example

curl "http://localhost:8080/v1/sandboxes/sbx_abc123/diagnostics/logs?scope=container" \
  -H "OPEN-SANDBOX-API-KEY: your-api-key"
Sample response (inline delivery): 
{
  "sandboxId": "sbx_abc123",
  "kind": "logs",
  "scope": "container",
  "delivery": "inline",
  "contentType": "text/plain; charset=utf-8",
  "content": "2026-03-25T10:01:13Z execd started\n2026-03-25T10:01:14Z sandbox process ready\n",
  "truncated": false
}
Sample response (URL delivery for large payloads): 
{
  "sandboxId": "sbx_abc123",
  "kind": "logs",
  "scope": "container",
  "delivery": "url",
  "contentType": "text/plain; charset=utf-8",
  "contentUrl": "https://example.com/diagnostics/sbx_abc123/logs.txt",
  "contentLength": 10485760,
  "expiresAt": "2026-04-14T10:30:00Z",
  "truncated": false
}

​
GET /v1/sandboxes//diagnostics/events

Retrieves a best-effort descriptor for sandbox diagnostic event text. Events are rendered as diagnostic text rather than a stable structured model. Depending on the scope and runtime, event text may include lifecycle transitions, Kubernetes Events, network diagnostic events, or process activity events. Auth: OPEN-SANDBOX-API-KEY header required.

​
Path Parameters

​
sandboxId
string
required
Unique sandbox identifier.

​
Query Parameters

​
scope
string
required
Diagnostic scope selector. Known values: container, lifecycle, runtime, network, process, all. Pass all for best-effort aggregate.

​
Response — 200 OK

The response schema is identical to the logs endpoint, with kind set to events.
​
sandboxId
string
required
Unique sandbox identifier.
​
kind
string
required
Value: events.
​
scope
string
required
Diagnostic scope used for this response.
​
delivery
string
required
Enum: inline, url.
​
contentType
string
required
Media type of the payload, e.g. "text/plain; charset=utf-8".
​
content
string
Inline event text. Present when delivery is inline.
​
contentUrl
string
Download URL. Present when delivery is url.
​
contentLength
integer
Payload size in bytes when known.
​
expiresAt
string
Download URL expiration (RFC 3339). Present when delivery is url.
​
truncated
boolean
required
Whether the payload was intentionally truncated.
​
warnings
array
Non-fatal warnings about payload completeness.

​
Example

curl "http://localhost:8080/v1/sandboxes/sbx_abc123/diagnostics/events?scope=runtime" \
  -H "OPEN-SANDBOX-API-KEY: your-api-key"
Sample response: 
{
  "sandboxId": "sbx_abc123",
  "kind": "events",
  "scope": "runtime",
  "delivery": "inline",
  "contentType": "text/plain; charset=utf-8",
  "content": "2026-03-25T10:01:13Z runtime Normal Scheduled Successfully assigned sandbox pod\n2026-03-25T10:01:14Z runtime Normal Pulled Container image pulled\n",
  "truncated": false
}

​
Diagnostic Scopes

ScopeDescription
containerSandbox container stdout/stderr and process output.
lifecycleLifecycle state transition events and provisioning diagnostic text.
runtimePlatform or orchestration-layer events (e.g. Kubernetes Events).
networkNetwork diagnostic text including egress policy and DNS events.
processProcess activity events within the sandbox.
allBest-effort aggregate across all supported scopes for this deployment.
Supported scopes are implementation-defined. Servers may expose only a subset of the scopes listed above, and may add new scopes in future versions. Requests for unsupported scopes return 501 Not Implemented.

​
Delivery Modes

DeliveryWhen UsedFields Present
inlinePayload fits within server response size limits.content
urlPayload exceeds size limits; a download URL is issued.contentUrl, expiresAt, contentLength
When delivery is url, download the content before expiresAt — the URL is time-limited. Check truncated: true to determine whether the server applied size limits to the returned content.

​
CLI Equivalent

The OpenSandbox CLI provides a convenient wrapper for these endpoints: 
osb diagnostics sbx_abc123 --scope lifecycle
osb diagnostics sbx_abc123 --scope container
osb diagnostics sbx_abc123 --scope runtime --kind events

Build docs developers (and LLMs) love

Get started for freeTalk to us