Connect directly to a viam-server instance running on a device to inspect resources, run operations, manage sessions, retrieve machine status and version, transform poses, and tunnel TCP traffic. The Robot Service is the entry point for every machine-side gRPC call.
openapi: 3.1.0
info:
title: Viam Machine Management API
description: |
REST/JSON transcoding of the Viam RobotService gRPC API. Connect to a viam-server
instance running on a device to inspect resources, manage sessions, retrieve status,
transform poses, and tunnel TCP traffic.
Canonical contract: https://github.com/viamrobotics/api/blob/main/proto/viam/robot/v1/robot.proto
version: '2026.05'
contact:
name: Viam Support
url: https://www.viam.com/contact
servers:
- url: https://{machine_address}
description: Per-machine viam-server endpoint (typically resolved through app.viam.com signaling)
variables:
machine_address:
default: machine.local.viam.cloud:443
security:
- ApiKeyAuth: []
tags:
- name: Operations
description: Long-running operations executing on the machine.
- name: Resources
description: Resources (components and services) registered on the machine.
- name: Sessions
description: Client sessions with safety-timeout heartbeats.
- name: Status
description: Status, version, cloud metadata, and machine state.
- name: Frame System
description: Frame system config and pose transformations.
- name: Modules
description: Modular component and service lifecycle.
- name: Tunneling
description: TCP tunneling through the machine.
paths:
/viam.robot.v1.RobotService/GetOperations:
post:
summary: Viam Get Operations
description: List operations currently running on the machine.
operationId: getOperations
tags: [Operations]
requestBody:
required: true
content:
application/json:
schema: { type: object }
responses:
'200':
description: Successful response.
/viam.robot.v1.RobotService/CancelOperation:
post:
summary: Viam Cancel Operation
description: Cancel a running operation by id.
operationId: cancelOperation
tags: [Operations]
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [id]
properties:
id: { type: string }
responses:
'200':
description: Successful response.
/viam.robot.v1.RobotService/BlockForOperation:
post:
summary: Viam Block For Operation
description: Block the caller until an operation completes.
operationId: blockForOperation
tags: [Operations]
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [id]
properties:
id: { type: string }
responses:
'200':
description: Successful response.
/viam.robot.v1.RobotService/ResourceNames:
post:
summary: Viam Resource Names
description: List all registered resource names on the machine.
operationId: resourceNames
tags: [Resources]
requestBody:
required: true
content:
application/json:
schema: { type: object }
responses:
'200':
description: Successful response.
/viam.robot.v1.RobotService/ResourceRPCSubtypes:
post:
summary: Viam Resource Rpc Subtypes
description: List supported resource RPC subtypes implemented on the machine.
operationId: resourceRPCSubtypes
tags: [Resources]
requestBody:
required: true
content:
application/json:
schema: { type: object }
responses:
'200':
description: Successful response.
/viam.robot.v1.RobotService/GetModelsFromModules:
post:
summary: Viam Get Models From Modules
description: Retrieve the list of resource models registered by all loaded modules.
operationId: getModelsFromModules
tags: [Modules]
requestBody:
required: true
content:
application/json:
schema: { type: object }
responses:
'200':
description: Successful response.
/viam.robot.v1.RobotService/RestartModule:
post:
summary: Viam Restart Module
description: Restart a loaded module without restarting viam-server.
operationId: restartModule
tags: [Modules]
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
module_id: { type: string }
module_name: { type: string }
responses:
'200':
description: Successful response.
/viam.robot.v1.RobotService/StartSession:
post:
summary: Viam Start Session
description: Open a new session with the machine.
operationId: startSession
tags: [Sessions]
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
resume: { type: string }
responses:
'200':
description: Successful response.
/viam.robot.v1.RobotService/SendSessionHeartbeat:
post:
summary: Viam Send Session Heartbeat
description: Send a heartbeat to keep the session alive.
operationId: sendSessionHeartbeat
tags: [Sessions]
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [id]
properties:
id: { type: string }
responses:
'200':
description: Successful response.
/viam.robot.v1.RobotService/GetSessions:
post:
summary: Viam Get Sessions
description: List active sessions on the machine.
operationId: getSessions
tags: [Sessions]
requestBody:
required: true
content:
application/json:
schema: { type: object }
responses:
'200':
description: Successful response.
/viam.robot.v1.RobotService/GetMachineStatus:
post:
summary: Viam Get Machine Status
description: Retrieve the overall machine status including each resource's state.
operationId: getMachineStatus
tags: [Status]
requestBody:
required: true
content:
application/json:
schema: { type: object }
responses:
'200':
description: Successful response.
/viam.robot.v1.RobotService/GetVersion:
post:
summary: Viam Get Version
description: Retrieve the viam-server version and platform metadata.
operationId: getVersion
tags: [Status]
requestBody:
required: true
content:
application/json:
schema: { type: object }
responses:
'200':
description: Successful response.
/viam.robot.v1.RobotService/GetCloudMetadata:
post:
summary: Viam Get Cloud Metadata
description: Retrieve the org/location/machine id that the device is registered to.
operationId: getCloudMetadata
tags: [Status]
requestBody:
required: true
content:
application/json:
schema: { type: object }
responses:
'200':
description: Successful response.
/viam.robot.v1.RobotService/Shutdown:
post:
summary: Viam Shutdown
description: Cleanly shut down viam-server on the device.
operationId: shutdown
tags: [Status]
requestBody:
required: true
content:
application/json:
schema: { type: object }
responses:
'200':
description: Successful response.
/viam.robot.v1.RobotService/StopAll:
post:
summary: Viam Stop All
description: Stop all components on the machine.
operationId: stopAll
tags: [Status]
requestBody:
required: true
content:
application/json:
schema: { type: object }
responses:
'200':
description: Successful response.
/viam.robot.v1.RobotService/FrameSystemConfig:
post:
summary: Viam Frame System Config
description: Retrieve the current frame system configuration.
operationId: frameSystemConfig
tags: [Frame System]
requestBody:
required: true
content:
application/json:
schema: { type: object }
responses:
'200':
description: Successful response.
/viam.robot.v1.RobotService/GetPose:
post:
summary: Viam Get Pose
description: Retrieve a component's pose relative to a destination frame.
operationId: getPose
tags: [Frame System]
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [component_name]
properties:
component_name: { type: string }
destination_frame: { type: string }
responses:
'200':
description: Successful response.
/viam.robot.v1.RobotService/TransformPose:
post:
summary: Viam Transform Pose
description: Transform a pose from one frame to another.
operationId: transformPose
tags: [Frame System]
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [source, destination]
properties:
source: { type: object }
destination: { type: string }
responses:
'200':
description: Successful response.
/viam.robot.v1.RobotService/TransformPCD:
post:
summary: Viam Transform Pcd
description: Transform a point cloud from one frame to another.
operationId: transformPCD
tags: [Frame System]
requestBody:
required: true
content:
application/json:
schema: { type: object }
responses:
'200':
description: Successful response.
/viam.robot.v1.RobotService/Log:
post:
summary: Viam Log
description: Submit log entries to viam-server.
operationId: log
tags: [Status]
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [logs]
properties:
logs: { type: array, items: { type: object } }
responses:
'200':
description: Successful response.
/viam.robot.v1.RobotService/Tunnel:
post:
summary: Viam Tunnel
description: Tunnel TCP traffic through viam-server (bidirectional stream).
operationId: tunnel
tags: [Tunneling]
requestBody:
required: true
content:
application/json:
schema: { type: object }
responses:
'200':
description: Successful response.
/viam.robot.v1.RobotService/ListTunnels:
post:
summary: Viam List Tunnels
description: List active tunnels.
operationId: listTunnels
tags: [Tunneling]
requestBody:
required: true
content:
application/json:
schema: { type: object }
responses:
'200':
description: Successful response.
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: key
description: Viam API key sent as gRPC metadata or location secret.