Review: OpenAPI REST API Spec

Overall this is a well-structured, professional spec. Good use of idempotency keys, pagination, SSE streaming, OAuth2 scopes, and WebSocket TTY. The schema mappings to Rust types (BoxInfo, BoxOptions, BoxCommand, RuntimeMetrics, BoxMetrics, ImageInfo) are accurate.

I pushed a commit fixing 3 bugs:

• ASF license header → replaced with BoxLite Contributors header (this isn't an ASF project)
• Contact URL → bxlite → boxlite-ai
• next-page-token → next_page_token (hyphenated JSON keys break code generation in Go/Python/Java/Rust)

Remaining suggestions

Should fix:

1. Box.updated_at vs Rust BoxInfo.last_updated — the Rust struct uses last_updated. Consider aligning the naming (either rename the Rust field or the spec field) to avoid confusion when implementing the adapter.

2. ErrorModel.type enum gaps — the spec says it "maps directly to BoxliteError variants" but:

   • Missing RpcTransport variant (exists in Rust)
   • UnsupportedError is ambiguous: Rust has both UnsupportedEngine (no payload) and Unsupported(String)
   • UnauthorizedError is cloud-only (doesn't exist in Rust) — worth documenting as such

3. labels field — CreateBoxRequest accepts labels and Box response returns them, but BoxOptions in Rust has no labels field. BoxInfo::new() hardcodes labels: HashMap::new(). Either add label storage to the core library or remove from spec until implemented.

Nice to have:

4. Missing GET /{prefix}/boxes/{box_id}/executions — there's GET /executions/{exec_id} to get one execution, but no way to list all executions for a box. Useful for debugging and monitoring.

5. Missing PATCH /{prefix}/boxes/{box_id} — no way to update mutable fields (labels, name) after creation.

6. network single-value enum — CreateBoxRequest.network is enum: [isolated]. Consider using plain type: string with a default: isolated instead, so adding new modes later doesn't break the enum contract.

7. BootTiming nesting — the spec groups boot timing into a nested BootTiming object, while Rust keeps stage_*_ms fields flat in BoxMetrics. This is a reasonable REST design choice, just noting the structural difference for implementers.

LGTM