Bear Robotics Robot System API

openapi: 3.2.0
info:
  title: Bear Cloud Robot System API
  description: "Bear Cloud APIs define the control, navigation, monitoring, and fleet management\n interface for robots."
  version: 1.3.0
servers:
- url: https://api.bearrobotics.ai
security:
- BearerAuth: []
tags:
- name: Robot System
  description: System-level operations and Queries for static robot configurations
paths:
  /v0/robot-system-info/get:
    post:
      tags:
      - Robot System
      description: "Get the overall robot system information.\n\n When called, the server returns robot system information. The system info\n tends to be static and does not change often."
      operationId: APIService_GetRobotSystemInfo
      requestBody:
        description: Robot identifier for system info retrieval
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - robotId
              properties:
                robotId:
                  type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetRobotSystemInfoResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
  /v1/system-command/run:
    post:
      tags:
      - Robot System
      description: "Execute a OS-level command on a robot.\n\n When rebooting the robot, a response will return immediately to acknowledge\n the request but may take several minutes before the robot reconnects."
      operationId: APIService_RunSystemCommand
      requestBody:
        description: Robot identifier and system command to execute
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunSystemCommandRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunSystemCommandResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
components:
  responses:
    Unauthorized:
      description: Unauthorized credentials, ensure the JWT is correct and up to date.
    GatewayTimeout:
      description: Server-side timeout, usually caused by the failure to send/receive commands/responses to the designated robot.
    BadRequest:
      description: Bad Request, usually caused by malfored request body.
      headers:
        grpc-status:
          schema:
            type: integer
          description: gRPC status code
        grpc-message:
          schema:
            type: string
          description: detailed error message
    ServiceUnavailable:
      description: Service is temporarily unavailable, which can usually be resolved by backoff retries.
    InternalServerError:
      description: Internal Server Error
  schemas:
    SystemInfo:
      type: object
      properties:
        softwareVersion:
          type: string
          description: "The distribution version currently installed and running on the robot.\n e.g. \"servi-24.03\""
        robotFamily:
          type: integer
          format: enum
        robotId:
          type: string
          description: Unique identifier for the robot. e.g. "pennybot-abc123"
        displayName:
          type: string
          description: A user-friendly name for the robot, typically used for display purposes.
      description: SystemInfo contains various system-level data of a robot.
    RunSystemCommandResponse:
      type: object
      properties: {}
    RunSystemCommandRequest:
      type: object
      required:
      - robotId
      - systemCommand
      properties:
        robotId:
          type: string
        systemCommand:
          type: object
          oneOf:
          - properties:
              reboot:
                type: object
                required:
                - type
                properties:
                  type:
                    type: integer
                    format: enum
                    description: Reboot type (e.g. software-only or full power-cycle). TYPE_UNKNOWN (0) is not allowed.
            required:
            - reboot
          - properties:
              shutdown:
                type: object
                properties: {}
            required:
            - shutdown
      description: Request object for running system commands
    GetRobotSystemInfoResponse:
      type: object
      properties:
        systemInfo:
          $ref: '#/components/schemas/SystemInfo'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token obtained from the /authorizeApiAccess endpoint