api-schema.yaml

openapi: 3.1.0
info:
  title: LeRobot Arena AI Server
  summary: ACT Model Inference Server for Real-time Robot Control
  description: "\n        ## LeRobot Arena AI Server\n\n        This server provides\
    \ **ACT (Action Chunking Transformer)** model inference for robotics applications.\n\
    \        It uses the LeRobot Arena communication system with multiple rooms per\
    \ session for:\n\n        ### Core Features:\n        - \U0001F3A5 **Multi-camera\
    \ support**: Arbitrary number of camera streams with unique names\n        - \U0001F916\
    \ **Joint control**: Normalized joint value handling (-100 to +100 range)\n  \
    \      - \U0001F504 **Real-time inference**: Optimized for robotics control loops\n\
    \        - \U0001F4CA **Session management**: Multiple concurrent inference sessions\n\
    \        - \U0001F6E0️ **Debug endpoints**: Comprehensive monitoring and debugging\
    \ tools\n\n        ### Communication Architecture:\n        1. **Camera rooms**:\
    \ Receives video streams from robot cameras (supports multiple cameras)\n    \
    \    2. **Joint input room**: Receives current robot joint positions (**NORMALIZED\
    \ VALUES**)\n        3. **Joint output room**: Sends predicted joint commands\
    \ (**NORMALIZED VALUES**)\n\n        ### Supported Cameras:\n        Each camera\
    \ stream has a unique name (e.g., \"front\", \"wrist\", \"overhead\") \n     \
    \   and all streams are synchronized for inference.\n\n        ### Joint Value\
    \ Convention:\n        - All joint inputs/outputs use **NORMALIZED VALUES**\n\
    \        - Range: -100 to +100 for most joints, 0 to 100 for gripper\n       \
    \ - Matches training data format exactly\n\n        ### Getting Started:\n   \
    \     1. Create a session with your trained ACT model\n        2. Connect your\
    \ robot to the generated rooms\n        3. Start inference to begin real-time\
    \ control\n        "
  version: 1.0.0
  contact:
    name: LeRobot Arena Team
    url: https://github.com/huggingface/lerobot
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  x-logo:
    url: https://huggingface.co/datasets/huggingface/brand-assets/resolve/main/hf-logo.png
    altText: LeRobot Logo
paths:
  /:
    get:
      tags:
      - Health
      summary: Root
      description: Health check endpoint.
      operationId: root__get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /health:
    get:
      tags:
      - Health
      summary: Health Check
      description: Detailed health check.
      operationId: health_check_health_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /sessions:
    get:
      tags:
      - Sessions
      summary: List Sessions
      description: List all sessions.
      operationId: list_sessions_sessions_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/SessionStatusResponse'
                type: array
                title: Response List Sessions Sessions Get
    post:
      tags:
      - Sessions
      summary: Create Session
      description: 'Create a new inference session.


        If workspace_id is provided, all rooms will be created in that workspace.

        If workspace_id is not provided, a new workspace will be generated automatically.

        All rooms for a session (cameras + joints) are always created in the same
        workspace.'
      operationId: create_session_sessions_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSessionRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSessionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sessions/{session_id}:
    get:
      tags:
      - Sessions
      summary: Get Session Status
      description: Get status of a specific session.
      operationId: get_session_status_sessions__session_id__get
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          title: Session Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionStatusResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Sessions
      summary: Delete Session
      description: Delete a session.
      operationId: delete_session_sessions__session_id__delete
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          title: Session Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sessions/{session_id}/start:
    post:
      tags:
      - Control
      summary: Start Inference
      description: Start inference for a session.
      operationId: start_inference_sessions__session_id__start_post
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          title: Session Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sessions/{session_id}/stop:
    post:
      tags:
      - Control
      summary: Stop Inference
      description: Stop inference for a session.
      operationId: stop_inference_sessions__session_id__stop_post
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          title: Session Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sessions/{session_id}/restart:
    post:
      tags:
      - Control
      summary: Restart Inference
      description: Restart inference for a session.
      operationId: restart_inference_sessions__session_id__restart_post
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          title: Session Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /debug/system:
    get:
      tags:
      - Debug
      summary: Get System Info
      description: Get system information for debugging.
      operationId: get_system_info_debug_system_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /debug/logs:
    get:
      tags:
      - Debug
      summary: Get Recent Logs
      description: Get recent log entries for debugging.
      operationId: get_recent_logs_debug_logs_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /debug/sessions/{session_id}/reset:
    post:
      tags:
      - Debug
      summary: Debug Reset Session
      description: Reset a session's internal state for debugging.
      operationId: debug_reset_session_debug_sessions__session_id__reset_post
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          title: Session Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /debug/sessions/{session_id}/queue:
    get:
      tags:
      - Debug
      summary: Get Session Queue Info
      description: Get detailed information about a session's action queue.
      operationId: get_session_queue_info_debug_sessions__session_id__queue_get
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          title: Session Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    CreateSessionRequest:
      properties:
        session_id:
          type: string
          title: Session Id
        policy_path:
          type: string
          title: Policy Path
        camera_names:
          items:
            type: string
          type: array
          title: Camera Names
          default:
          - front
        arena_server_url:
          type: string
          title: Arena Server Url
          default: http://localhost:8000
        workspace_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Workspace Id
      type: object
      required:
      - session_id
      - policy_path
      title: CreateSessionRequest
    CreateSessionResponse:
      properties:
        workspace_id:
          type: string
          title: Workspace Id
        camera_room_ids:
          additionalProperties:
            type: string
          type: object
          title: Camera Room Ids
        joint_input_room_id:
          type: string
          title: Joint Input Room Id
        joint_output_room_id:
          type: string
          title: Joint Output Room Id
      type: object
      required:
      - workspace_id
      - camera_room_ids
      - joint_input_room_id
      - joint_output_room_id
      title: CreateSessionResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    SessionStatusResponse:
      properties:
        session_id:
          type: string
          title: Session Id
        status:
          type: string
          title: Status
        policy_path:
          type: string
          title: Policy Path
        camera_names:
          items:
            type: string
          type: array
          title: Camera Names
        workspace_id:
          type: string
          title: Workspace Id
        rooms:
          additionalProperties: true
          type: object
          title: Rooms
        stats:
          additionalProperties: true
          type: object
          title: Stats
        inference_stats:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Inference Stats
        error_message:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Message
      type: object
      required:
      - session_id
      - status
      - policy_path
      - camera_names
      - workspace_id
      - rooms
      - stats
      title: SessionStatusResponse
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
servers:
- url: http://localhost:8001
  description: Development server
- url: https://your-production-server.com
  description: Production server
tags:
- name: Health
  description: Health check and server status endpoints
- name: Sessions
  description: Inference session management - create, control, and monitor AI sessions
- name: Control
  description: Session control operations - start, stop, restart inference
- name: Debug
  description: Debug and monitoring endpoints for system diagnostics