openapi: 3.1.0
info:
  title: Hanzo Exec API
  description: |
    Code Interpreter ("Run Code") surface on the unified cloud-api /v1 plane
    (`hanzoai/cloud/clients/exec`), per HIP-0106. A thin reverse proxy that
    forwards each request UNCHANGED to a sandboxed executor upstream — no code
    runs in the cloud binary. The contract is the LibreChat code-interpreter
    contract: POST `{lang, code, files?}` to `/v1/exec`, with sibling paths for
    programmatic execution, uploads, downloads and per-session file listing.

    AUTH: this surface is called server-side by the chat node process with a
    shared service key on the `X-API-Key` header (NOT a user JWT — the gateway
    bypasses these paths). An unset key fails closed (503); a wrong key is 401.
  version: 8.0.0
  contact:
    name: Hanzo AI
    url: https://hanzo.ai
    email: support@hanzo.ai
  license:
    name: Proprietary
servers:
  - url: https://api.hanzo.ai
    description: Hanzo Gateway
tags:
  - name: Exec
    description: Sandboxed code execution
  - name: Files
    description: Session file upload / download / listing
security:
  - serviceKey: []
paths:
  /v1/exec:
    post:
      tags: [Exec]
      summary: Execute code in a sandboxed session
      operationId: execCode
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ExecRequest' }
      responses:
        '200': { description: Execution result, content: { application/json: { schema: { $ref: '#/components/schemas/ExecResult' } } } }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '503': { $ref: '#/components/responses/NotConfigured' }

  /v1/exec/programmatic:
    post:
      tags: [Exec]
      summary: Programmatic code execution (sibling of /v1/exec, same executor contract)
      operationId: execProgrammatic
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ExecRequest' }
      responses:
        '200': { description: Execution result, content: { application/json: { schema: { $ref: '#/components/schemas/ExecResult' } } } }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '503': { $ref: '#/components/responses/NotConfigured' }

  /v1/upload:
    post:
      tags: [Files]
      summary: Upload a file into a session
      operationId: uploadFile
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file: { type: string, format: binary }
                session_id: { type: string }
      responses:
        '200': { description: Uploaded, content: { application/json: { schema: { type: object, properties: { session_id: { type: string }, files: { type: array, items: { $ref: '#/components/schemas/ExecFile' } } } } } } }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '503': { $ref: '#/components/responses/NotConfigured' }

  /v1/download/{id}:
    get:
      tags: [Files]
      summary: Download a produced file by id
      operationId: downloadFile
      parameters:
        - { name: id, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: File contents, content: { application/octet-stream: { schema: { type: string, format: binary } } } }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '503': { $ref: '#/components/responses/NotConfigured' }

  /v1/files/{session_id}:
    get:
      tags: [Files]
      summary: List the files produced in a session
      operationId: listSessionFiles
      parameters:
        - { name: session_id, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: Files, content: { application/json: { schema: { type: object, properties: { files: { type: array, items: { $ref: '#/components/schemas/ExecFile' } } } } } } }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '503': { $ref: '#/components/responses/NotConfigured' }

components:
  securitySchemes:
    serviceKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: Shared service key (KMS-sourced) presented server-side by the chat node process. Not a user JWT.
    bearerAuth:
      type: http
      scheme: bearer
      description: IAM-issued JWT or `hk-` Cloud API key.
  responses:
    Unauthorized:
      description: Missing or invalid credentials
      content:
        application/json:
          schema: { type: object, properties: { status: { type: integer }, error: { type: string } } }
    NotConfigured:
      description: Code execution not configured on this deployment (service key unset — fail-closed)
      content:
        application/json:
          schema: { type: object, properties: { status: { type: integer }, error: { type: string } } }
  schemas:
    ExecRequest:
      type: object
      required: [lang, code]
      properties:
        lang: { type: string, description: "Language / runtime (e.g. python, node)" }
        code: { type: string }
        files: { type: array, description: Optional input files, items: { $ref: '#/components/schemas/ExecFile' } }
    ExecFile:
      type: object
      properties:
        name: { type: string }
    ExecResult:
      type: object
      properties:
        session_id: { type: string }
        stdout: { type: string }
        stderr: { type: string }
        files: { type: array, items: { $ref: '#/components/schemas/ExecFile' } }