wehub-resource-sync
e0e362d700
SDK Tests / changes (push) Successful in 2m29s
Real E2E Tests / changes (push) Successful in 2m29s
Deploy Docs Pages / build (push) Has been cancelled
Deploy Docs Pages / deploy (push) Has been cancelled
Real E2E Tests / JavaScript E2E (docker bridge) (push) Has been cancelled
Real E2E Tests / Python E2E (docker bridge) (push) Has been cancelled
Real E2E Tests / Java E2E (docker bridge) (push) Has been cancelled
Real E2E Tests / C# E2E (docker bridge) (push) Has been cancelled
Real E2E Tests / Go E2E (docker bridge) (push) Has been cancelled
Real E2E Tests / Real E2E CI (push) Has been cancelled
SDK Tests / SDK CI (push) Has been cancelled
SDK Tests / CLI Tests (push) Has been cancelled
SDK Tests / Python SDK Quality (code-interpreter) (push) Has been cancelled
SDK Tests / Python SDK Quality (sandbox) (push) Has been cancelled
SDK Tests / Python SDK Tests (code-interpreter) (push) Has been cancelled
SDK Tests / JavaScript SDK Quality And Tests (code-interpreter) (push) Has been cancelled
SDK Tests / JavaScript SDK Quality And Tests (sandbox) (push) Has been cancelled
SDK Tests / Python SDK Tests (sandbox) (push) Has been cancelled
SDK Tests / CLI Quality (push) Has been cancelled
SDK Tests / Kotlin SDK Quality And Tests (sandbox) (push) Has been cancelled
SDK Tests / Kotlin SDK Quality And Tests (code-interpreter) (push) Has been cancelled
SDK Tests / C# SDK Quality And Tests (code-interpreter) (push) Has been cancelled
SDK Tests / C# SDK Quality And Tests (sandbox) (push) Has been cancelled
SDK Tests / Go SDK Quality And Tests (push) Has been cancelled
359 lines
13 KiB
YAML
359 lines
13 KiB
YAML
openapi: 3.1.0
|
|
info:
|
|
title: OpenSandbox Diagnostics API
|
|
version: 0.1.0
|
|
description: |
|
|
The OpenSandbox Diagnostics API exposes best-effort plain-text diagnostic
|
|
snapshots for a sandbox. It is intended for humans and troubleshooting agents
|
|
that need to collect runtime troubleshooting material without depending on a
|
|
stable structured observability model.
|
|
|
|
This API is not an audit log API and does not define the canonical
|
|
observability schema for OpenSandbox. Structured telemetry, long-term
|
|
retention, filtering, pagination, and streaming may be provided separately.
|
|
|
|
Successful responses return a JSON descriptor whose diagnostic payload is
|
|
either embedded inline or made available through a download URL. The diagnostic
|
|
payload itself is display-oriented `text/plain` content. Clients should not
|
|
parse individual payload lines as a stable schema. Servers may impose
|
|
implementation-defined retention and response size limits.
|
|
|
|
## Authentication
|
|
|
|
API Key authentication is required for all operations:
|
|
|
|
1. **HTTP Header**
|
|
```
|
|
OPEN-SANDBOX-API-KEY: your-api-key
|
|
```
|
|
|
|
2. **Environment Variable** (for SDK clients)
|
|
```
|
|
OPEN_SANDBOX_API_KEY=your-api-key
|
|
```
|
|
|
|
SDK clients will automatically pick up this environment variable.
|
|
servers:
|
|
- url: http://localhost:8080/v1
|
|
description: Local development
|
|
security:
|
|
- apiKeyAuth: []
|
|
tags:
|
|
- name: Diagnostics
|
|
description: Sandbox troubleshooting payload descriptors
|
|
paths:
|
|
/sandboxes/{sandboxId}/diagnostics/logs:
|
|
get:
|
|
tags: [Diagnostics]
|
|
summary: Get diagnostic logs
|
|
description: |
|
|
Retrieve a best-effort descriptor for sandbox diagnostic log text.
|
|
|
|
Logs are not limited to a structured observability model. 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.
|
|
|
|
This endpoint does not provide streaming, pagination, or a stable line-level
|
|
schema in this version. The server returns a JSON descriptor for currently
|
|
available diagnostic text for the requested scope, subject to
|
|
implementation-defined retention and response size limits. The descriptor
|
|
either embeds the text as `content` or returns a `contentUrl` where the
|
|
text can be downloaded.
|
|
parameters:
|
|
- $ref: '#/components/parameters/SandboxId'
|
|
- $ref: '#/components/parameters/DiagnosticScope'
|
|
responses:
|
|
'200':
|
|
description: Diagnostic log content descriptor
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/DiagnosticContentResponse'
|
|
examples:
|
|
inline:
|
|
summary: Inline container log text
|
|
value:
|
|
sandboxId: sbx_123
|
|
kind: logs
|
|
scope: container
|
|
delivery: inline
|
|
contentType: text/plain; charset=utf-8
|
|
content: |
|
|
2026-03-25T10:01:13Z execd started
|
|
2026-03-25T10:01:14Z sandbox process ready
|
|
truncated: false
|
|
url:
|
|
summary: Downloadable container log text
|
|
value:
|
|
sandboxId: sbx_123
|
|
kind: logs
|
|
scope: container
|
|
delivery: url
|
|
contentType: text/plain; charset=utf-8
|
|
contentUrl: https://example.com/diagnostics/sbx_123/logs.txt
|
|
contentLength: 10485760
|
|
expiresAt: "2026-04-14T10:30:00Z"
|
|
truncated: false
|
|
headers:
|
|
X-Request-ID:
|
|
$ref: '#/components/headers/XRequestId'
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'403':
|
|
$ref: '#/components/responses/Forbidden'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
'500':
|
|
$ref: '#/components/responses/InternalServerError'
|
|
'501':
|
|
$ref: '#/components/responses/NotImplemented'
|
|
/sandboxes/{sandboxId}/diagnostics/events:
|
|
get:
|
|
tags: [Diagnostics]
|
|
summary: Get diagnostic events
|
|
description: |
|
|
Retrieve a best-effort descriptor for sandbox diagnostic event text.
|
|
|
|
Events are rendered as diagnostic text rather than exposed as a stable
|
|
structured event model. Depending on the selected `scope` and runtime, event
|
|
text may include lifecycle transitions, runtime or platform events such as
|
|
Kubernetes Events, network diagnostic events, process activity events, or
|
|
other implementation-defined event material.
|
|
|
|
This endpoint does not provide streaming, pagination, or a stable line-level
|
|
schema in this version. The server returns a JSON descriptor for currently
|
|
available diagnostic event text for the requested scope, subject to
|
|
implementation-defined retention and response size limits. The descriptor
|
|
either embeds the text as `content` or returns a `contentUrl` where the
|
|
text can be downloaded.
|
|
parameters:
|
|
- $ref: '#/components/parameters/SandboxId'
|
|
- $ref: '#/components/parameters/DiagnosticScope'
|
|
responses:
|
|
'200':
|
|
description: Diagnostic event content descriptor
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/DiagnosticContentResponse'
|
|
examples:
|
|
inline:
|
|
summary: Inline runtime event text
|
|
value:
|
|
sandboxId: sbx_123
|
|
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
|
|
2026-03-25T10:01:14Z runtime Normal Pulled Container image pulled
|
|
truncated: false
|
|
url:
|
|
summary: Downloadable runtime event text
|
|
value:
|
|
sandboxId: sbx_123
|
|
kind: events
|
|
scope: runtime
|
|
delivery: url
|
|
contentType: text/plain; charset=utf-8
|
|
contentUrl: https://example.com/diagnostics/sbx_123/events.txt
|
|
contentLength: 5242880
|
|
expiresAt: "2026-04-14T10:30:00Z"
|
|
truncated: false
|
|
headers:
|
|
X-Request-ID:
|
|
$ref: '#/components/headers/XRequestId'
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'403':
|
|
$ref: '#/components/responses/Forbidden'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
'500':
|
|
$ref: '#/components/responses/InternalServerError'
|
|
'501':
|
|
$ref: '#/components/responses/NotImplemented'
|
|
components:
|
|
securitySchemes:
|
|
apiKeyAuth:
|
|
type: apiKey
|
|
in: header
|
|
name: OPEN-SANDBOX-API-KEY
|
|
description: |
|
|
API Key for authentication. Can be provided via:
|
|
1. HTTP Header: OPEN-SANDBOX-API-KEY: your-api-key
|
|
2. Environment variable: OPEN_SANDBOX_API_KEY (for SDK clients)
|
|
parameters:
|
|
SandboxId:
|
|
name: sandboxId
|
|
in: path
|
|
required: true
|
|
description: Unique sandbox identifier
|
|
schema:
|
|
type: string
|
|
DiagnosticScope:
|
|
name: scope
|
|
in: query
|
|
required: true
|
|
description: |
|
|
Required diagnostic scope selector. Known scopes may include `container`,
|
|
`lifecycle`, `runtime`, `network`, `process`, and `all`. Supported scopes
|
|
are implementation-defined; servers may add new scopes over time.
|
|
|
|
On deployments that still expose the legacy DevOps plain-text behavior on
|
|
this path, requests without `scope` are treated as deprecated legacy
|
|
requests and may return `text/plain` instead of this JSON descriptor.
|
|
schema:
|
|
type: string
|
|
examples:
|
|
container:
|
|
summary: Sandbox container diagnostics
|
|
value: container
|
|
runtime:
|
|
summary: Runtime or platform diagnostics
|
|
value: runtime
|
|
all:
|
|
summary: Best-effort aggregate across supported scopes
|
|
value: all
|
|
headers:
|
|
XRequestId:
|
|
description: Unique request identifier for tracing
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
responses:
|
|
BadRequest:
|
|
description: The request was invalid or malformed
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
headers:
|
|
X-Request-ID:
|
|
$ref: '#/components/headers/XRequestId'
|
|
Unauthorized:
|
|
description: Authentication credentials are missing or invalid
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
headers:
|
|
X-Request-ID:
|
|
$ref: '#/components/headers/XRequestId'
|
|
Forbidden:
|
|
description: The authenticated user lacks permission for this operation
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
headers:
|
|
X-Request-ID:
|
|
$ref: '#/components/headers/XRequestId'
|
|
NotFound:
|
|
description: The requested sandbox does not exist
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
headers:
|
|
X-Request-ID:
|
|
$ref: '#/components/headers/XRequestId'
|
|
InternalServerError:
|
|
description: An unexpected server error occurred
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
headers:
|
|
X-Request-ID:
|
|
$ref: '#/components/headers/XRequestId'
|
|
NotImplemented:
|
|
description: The stable Diagnostics API is not implemented by this server
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
headers:
|
|
X-Request-ID:
|
|
$ref: '#/components/headers/XRequestId'
|
|
schemas:
|
|
DiagnosticContentResponse:
|
|
type: object
|
|
description: |
|
|
Descriptor for diagnostic text content.
|
|
|
|
When `delivery` is `inline`, servers MUST include `content` with the
|
|
diagnostic text and MUST omit `contentUrl` / `expiresAt`.
|
|
|
|
When `delivery` is `url`, servers MUST include `contentUrl` and `expiresAt`
|
|
to identify where the diagnostic text can be downloaded and MUST omit
|
|
`content`.
|
|
required: [sandboxId, kind, scope, delivery, contentType, truncated]
|
|
properties:
|
|
sandboxId:
|
|
type: string
|
|
description: Unique sandbox identifier.
|
|
kind:
|
|
type: string
|
|
description: Diagnostic payload kind.
|
|
enum: [logs, events]
|
|
scope:
|
|
type: string
|
|
description: Diagnostic scope used for this response.
|
|
delivery:
|
|
type: string
|
|
description: How the diagnostic text payload is delivered.
|
|
enum: [inline, url]
|
|
contentType:
|
|
type: string
|
|
description: Media type of the diagnostic payload.
|
|
examples: ["text/plain; charset=utf-8"]
|
|
content:
|
|
type: string
|
|
description: Inline diagnostic text payload. Present when `delivery` is `inline`.
|
|
contentUrl:
|
|
type: string
|
|
format: uri
|
|
description: URL where the diagnostic text payload can be downloaded. Present when `delivery` is `url`.
|
|
contentLength:
|
|
type: integer
|
|
minimum: 0
|
|
description: Payload size in bytes when known.
|
|
expiresAt:
|
|
type: string
|
|
format: date-time
|
|
description: Expiration time for the download URL. Present when `delivery` is `url`.
|
|
truncated:
|
|
type: boolean
|
|
description: |
|
|
Whether the diagnostic payload returned inline or by URL was
|
|
intentionally truncated by the server. This does not indicate backend
|
|
retention gaps such as expired Kubernetes Events; those should be
|
|
reported through `warnings` when available.
|
|
warnings:
|
|
type: array
|
|
description: Non-fatal warnings about payload completeness or availability.
|
|
items:
|
|
type: string
|
|
additionalProperties: false
|
|
ErrorResponse:
|
|
type: object
|
|
description: |
|
|
Standard error response for all non-2xx HTTP responses.
|
|
HTTP status code indicates the error category; code and message provide details.
|
|
properties:
|
|
code:
|
|
type: string
|
|
description: Machine-readable error code.
|
|
message:
|
|
type: string
|
|
description: Human-readable error message describing what went wrong.
|
|
required: [code, message]
|
|
additionalProperties: false
|