Bear Robotics Locations & Maps API

openapi: 3.2.0
info:
  title: Bear Cloud Locations & Maps API
  description: 'Bear Cloud APIs define the control, navigation, monitoring, and fleet management

    interface for robots.'
  version: 1.3.0
servers:
- url: https://api.bearrobotics.ai
security:
- BearerAuth: []
tags:
- name: Locations & Maps
  description: Operations for fetching and setting location and map settings
paths:
  /v1/current-map/get:
    post:
      tags:
      - Locations & Maps
      description: 'Retrieves the current map used by the robot.


        The returned map includes annotations and destinations, which can be used

        in mission destination, localization goals, and navigation.


        Note:

        - This API communicates directly with the robot.

        - image_url may be empty, as the robot does not serve rendered images.'
      operationId: APIService_GetCurrentMap
      requestBody:
        description: Robot identifier for map 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/GetCurrentMapResponse'
        '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'
      summary: API service get current map
      x-summary-source: derived
  /v1/location-info/get:
    post:
      tags:
      - Locations & Maps
      description: 'Retrieve information about a specific location by its ID.


        The location includes metadata such as floors, sections, and their

        associated maps.


        Note:

        - This does not require robot connectivity.'
      operationId: APIService_GetLocationInfo
      requestBody:
        description: Location identifier for info retrieval
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetLocationInfoRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetLocationInfoResponse'
        '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'
      summary: API service get location info
      x-summary-source: derived
  /v1/map/get:
    post:
      tags:
      - Locations & Maps
      description: 'Retrieve a saved map by map_id from the cloud.


        Use this to fetch a stored map from the cloud database.


        Note:

        - This does not require robot connectivity.'
      operationId: APIService_GetMap
      requestBody:
        description: Map identifier for retrieval
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetMapRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMapResponse'
        '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'
      summary: API service get map
      x-summary-source: derived
  /v1/map/switch:
    post:
      tags:
      - Locations & Maps
      description: 'Switch the robot''s current map to a specified map.


        The request must specify the floor level and section index of the desired

        map.

        Returns an INVALID_ARGUMENT error if there is no matching map.

        Returns the map_id of the new map if successful.'
      operationId: APIService_SwitchMap
      requestBody:
        description: Robot identifier and map selector for switching maps
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SwitchMapRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SwitchMapResponse'
        '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'
      summary: API service switch map
      x-summary-source: derived
components:
  responses:
    GatewayTimeout:
      description: Server-side timeout, usually caused by the failure to send/receive commands/responses to the designated robot.
    InternalServerError:
      description: Internal Server Error
    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.
    Unauthorized:
      description: Unauthorized credentials, ensure the JWT is correct and up to date.
  schemas:
    MapImageFileInfo:
      type: object
      properties:
        checksum:
          type: integer
          description: '[Deprecated] CRC32C checksum of the map image file. Use md5Checksum instead.'
          format: uint32
          deprecated: true
        size:
          type: string
          description: Size of the map image file in bytes.
        md5Checksum:
          type: string
          description: MD5 checksum represented as a 32-character lowercase hexadecimal string.
      description: MapImageFileInfo contains metadata about the map image file for integrity verification.
    GetLocationInfoResponse:
      type: object
      properties:
        location:
          $ref: '#/components/schemas/Location'
    Floor_Section:
      type: object
      properties:
        displayName:
          type: string
          description: Display name of the section, matching the name shown in Universe.
        currentMapId:
          type: string
          description: ID of the current map associated with the section.
      description: "Represents a section of a floor.\n Each Section corresponds to an area on a floor that may have its own\n map(s). We assume sections are disconnected; if connected sections are\n needed in the future, additional information will be added to represent\n the connections."
    Destination:
      type: object
      properties:
        destinationId:
          type: string
          description: Unique identifier for the destination.
        displayName:
          type: string
          description: Human-readable name for the destination.
        pose:
          allOf:
          - $ref: '#/components/schemas/Pose'
          description: Position of the destination in the robot's map coordinate system.
      description: "Destination represents a single point of interest on the map\n that a robot can navigate to and align itself with."
    Location:
      type: object
      properties:
        locationId:
          type: string
          description: "A 4 character alphanumeric identifier for the location. This is unique\n among all locations in a Universe.\n Example: \"3R0A\"\n Legacy locations may use the display_name as the identifier, in which case\n the identifier may be longer or shorter than 4 characters."
        createdTime:
          type: string
          description: Timestamp indicating when the location was created.
          format: date-time
        modifiedTime:
          type: string
          description: Timestamp indicating the last time the location was modified.
          format: date-time
        displayName:
          type: string
          description: "Display name of the location, matching the name shown in Universe.\n Examples: \"City Deli & Grill\", \"KNTH\""
        floors:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Location_Floor'
          description: "Map of floors in the location, keyed by their floor level.\n The floor level is any non-negative integer starting from 0.\n Floor level is not necessarily sequential.\n Example:\n floors [\n   {\n     key: 0\n     value: {\n       display_name: \"Ground Floor\"\n       sections: [...]\n     }\n   }\n   {\n     key: 1\n     value: {\n       display_name: \"Second Floor\"\n       sections: [...]\n     }\n   }\n   {\n     key: 99\n     value: {\n       display_name: \"Roof\"\n       sections: [...]\n     }\n   }\n ]"
      description: "Location represents a physical location with multiple floors and sections,\n including metadata such as creation and modification timestamps."
    Pose:
      type: object
      properties:
        xMeters:
          type: number
          description: X-coordinate in meters within the map.
          format: float
        yMeters:
          type: number
          description: Y-coordinate in meters within the map.
          format: float
        headingRadians:
          type: number
          description: "The heading of the robot in radians.\n Ranges from -π to π, where 0.0 points along the positive x-axis."
          format: float
      description: Represents the robot's pose on the map.
    MapImageDownloadInfo:
      type: object
      properties:
        fileInfo:
          allOf:
          - $ref: '#/components/schemas/MapImageFileInfo'
          description: Information about the map image file for integrity verification.
        downloadUrl:
          allOf:
          - $ref: '#/components/schemas/SignedURL'
          description: The signed URL for downloading the map image.
      description: MapImageDownloadInfo contains the information needed to download a map image.
    SignedURL:
      type: object
      properties:
        url:
          type: string
        expiresAt:
          type: string
          format: date-time
      description: SignedURL represents a signed URL for file access with expiration.
    GetCurrentMapResponse:
      type: object
      properties:
        map:
          $ref: '#/components/schemas/Map'
    GetLocationInfoRequest:
      type: object
      required:
      - locationId
      properties:
        locationId:
          type: string
          description: "The location_id is a 4 character alphanumeric identifier for the location.\n Example: \"3R0A\""
      description: Request object for retrieving location information
    Origin:
      type: object
      properties:
        xM:
          type: number
          description: X-coordinate of the map origin in meters.
          format: float
        yM:
          type: number
          description: Y-coordinate of the map origin in meters.
          format: float
        yawRadians:
          type: number
          description: Orientation (yaw) of the map origin in radians.
          format: float
      description: Origin represents the starting point of the map in terms of its coordinates and orientation.
    Location_Floor:
      type: object
      properties:
        displayName:
          type: string
          description: "Display name of the floor, matching the name shown in Universe.\n Example: \"Ground\""
        sections:
          type: array
          items:
            $ref: '#/components/schemas/Floor_Section'
          description: List of sections on this floor.
      description: "Floor represents a single floor in the location, containing multiple\n sections."
    Map:
      type: object
      properties:
        mapId:
          type: string
          description: "Unique identifier for the map.\n Example: \"9578\""
        createdTime:
          type: string
          description: Timestamp indicating when the map was created.
          format: date-time
        modifiedTime:
          type: string
          description: Timestamp indicating the last time the map was modified.
          format: date-time
        displayName:
          type: string
          description: "Display name of the map, matching the name used in Bear Universe.\n Example: \"ITCT SEOUL\""
        annotation:
          allOf:
          - $ref: '#/components/schemas/Annotation'
          description: Annotation associated with this map, defining specific areas and destinations.
        imageDownloadInfo:
          allOf:
          - $ref: '#/components/schemas/MapImageDownloadInfo'
          description: "Information for downloading the map image, including signed URL and file metadata.\n This field is typically populated by the cloud service.\n When retrieving map data directly from the robot (e.g., via GetCurrentMap),\n this value may be empty."
        origin:
          allOf:
          - $ref: '#/components/schemas/Origin'
          description: Origin of the map relative to the map frame.
        resolution:
          type: number
          description: Resolution of the map in meters per pixel.
          format: float
      description: Map represents a navigable map used by robots, including metadata and associated annotations.
    GetMapRequest:
      type: object
      required:
      - mapId
      properties:
        mapId:
          type: string
      description: Request object for retrieving a saved map
    Annotation:
      type: object
      properties:
        annotationId:
          type: string
          description: "Unique identifier for the annotation.\n Example: \"67305\""
        displayName:
          type: string
          description: "Descriptive name for the annotation.\n Example: \"ITCT annotation A\""
        createdTime:
          type: string
          description: Timestamp indicating when the annotation was created.
          format: date-time
        destinations:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Destination'
          description: "A collection of destinations associated with this annotation.\n Each entry pairs a destination ID (key) with its\n corresponding Destination message (value)."
      description: "Annotation defines a specific area on the map, often used to\n group destinations or assign special parameters."
    SwitchMapRequest:
      type: object
      required:
      - robotId
      - mapSelector
      properties:
        robotId:
          type: string
        mapSelector:
          type: object
          required:
          - floorLevel
          - sectionIndex
          properties:
            floorLevel:
              type: integer
              format: int32
              description: Positive integer floor_level begins at 1.
            sectionIndex:
              type: integer
              format: int32
              description: Non-negative integer section_index begins at 0.
      description: Request object for switching robot maps
    GetMapResponse:
      type: object
      properties:
        map:
          $ref: '#/components/schemas/Map'
    SwitchMapResponse:
      type: object
      properties:
        mapId:
          type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token obtained from the /authorizeApiAccess endpoint
x-provenance:
  method: harvested
  publisher: Bear Robotics
  source: https://cloud.api.bearrobotics.ai/v1.3/resources/RestAPI/openapi-v1-3.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)