Bear Robotics Fleet Management API

openapi: 3.2.0
info:
  title: Bear Cloud Fleet Management 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: Fleet Management
  description: Fleet-level operations
paths:
  /v1/available-locations/get:
    post:
      tags:
      - Fleet Management
      description: 'Return a map of locations of the user has access to.


        The map consists of the location ID (key) paired with its human-readable

        name (value).'
      operationId: APIService_GetAvailableLocations
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAvailableLocationsResponse'
        '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/robot-ids/list:
    post:
      tags:
      - Fleet Management
      description: "Return a list of robot IDs the user has access to, filtered by optional\n criteria.\n\n The list includes all known robots, regardless of their current connection\n status."
      operationId: APIService_ListRobotIDs
      requestBody:
        description: Filter criteria for robot listing
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListRobotIDsRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListRobotIDsResponse'
        '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:
    ListRobotIDsResponse:
      type: object
      properties:
        totalRobots:
          type: integer
          format: int32
        robotIds:
          type: array
          items:
            type: string
          description: "This might not have all the robot IDs if there are too many.\n It will have all the robot IDs if the number of robot_ids is same as\n total_robots."
    RobotFilter:
      type: object
      properties:
        locationId:
          type: string
          description: "An empty location_id returns all robots authorized\n to the authenticated API key user."
      description: RobotFilter defines a filter for selecting robots.
    ListRobotIDsRequest:
      type: object
      properties:
        filter:
          allOf:
          - $ref: '#/components/schemas/RobotFilter'
          description: Filter for selecting which robots to list. If omitted, all authorized robots are returned.
      description: Request object for listing robot IDs
    GetAvailableLocationsResponse:
      type: object
      properties:
        locations:
          type: object
          additionalProperties:
            type: string
          description: "A mapping of location ID (key) with its corresponding, human-readable\n location name.\n e.g. { \"1D9X\": \"785_Platform\" }"
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token obtained from the /authorizeApiAccess endpoint