openapi: 3.1.0
info:
  title: KioWare Reference API Preview
  version: 0.8.0-preview
  description: Reference-only contract for architecture workshops. Production endpoints and scopes are issued per project.
servers:
  - url: https://sandbox.example.internal
    description: Placeholder only - request an assigned sandbox URL
paths:
  /v1/sessions:
    post:
      summary: Create a Kiosk session
      operationId: createSession
      parameters:
        - in: header
          name: Idempotency-Key
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [kioskId, applicationId]
              properties:
                kioskId: { type: string }
                applicationId: { type: string }
                locale: { type: string, default: vi-VN }
      responses:
        '201':
          description: Session created
          content:
            application/json:
              schema:
                type: object
                properties:
                  sessionId: { type: string }
                  traceId: { type: string }
                  expiresAt: { type: string, format: date-time }
  /v1/kiosks/{kioskId}/capabilities:
    get:
      summary: List available device capabilities
      operationId: listCapabilities
      parameters:
        - in: path
          name: kioskId
          required: true
          schema: { type: string }
      responses:
        '200': { description: Capability state returned }
  /v1/sessions/{sessionId}/commands:
    post:
      summary: Submit a policy-controlled device command
      operationId: submitCommand
      parameters:
        - in: path
          name: sessionId
          required: true
          schema: { type: string }
        - in: header
          name: Idempotency-Key
          required: true
          schema: { type: string }
      responses:
        '202': { description: Command accepted for execution }
  /v1/events:
    get:
      summary: Reference event-stream discovery endpoint
      responses:
        '200': { description: Event-stream metadata }
components:
  securitySchemes:
    bearerAuth: { type: http, scheme: bearer, bearerFormat: JWT }
security:
  - bearerAuth: []
