Viam

Viam Motion Service API

Plan and execute motion for a machine's components — Move, MoveOnMap, MoveOnGlobe, GetPose, StopPlan, ListPlanStatuses, GetPlan. Runs on viam-server as a machine-level service combining kinematic chains, frame system, and obstacle avoidance.

Viam Motion Service API is one of 14 APIs that Viam publishes on the APIs.io network, described by a machine-readable OpenAPI specification.

This API exposes 1 machine-runnable capability that can be deployed as REST, MCP, or Agent Skill surfaces via Naftiko.

Tagged areas include Robotics, Motion Planning, and Services. The published artifact set on APIs.io includes API documentation, an OpenAPI specification, and 1 Naftiko capability spec.

Documentation GitHub OpenAPI

OpenAPI Specification

openapi: 3.1.0
info:
  title: Viam Motion Service API
  description: |
    REST/JSON transcoding of the Viam MotionService gRPC API. Plan and execute motion
    for a machine's components using kinematic chains, the frame system, and obstacle
    avoidance.

    Canonical contract: https://github.com/viamrobotics/api/blob/main/proto/viam/service/motion/v1/motion.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.
    variables:
      machine_address:
        default: machine.local.viam.cloud:443
security:
  - ApiKeyAuth: []
tags:
  - name: Motion
    description: Plan and execute motion across components.
paths:
  /viam.service.motion.v1.MotionService/Move:
    post:
      summary: Viam Move
      description: Plan and execute a motion to a destination pose for a component.
      operationId: move
      tags: [Motion]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, component_name, destination]
              properties:
                name: { type: string }
                component_name: { type: object }
                destination: { type: object }
                world_state: { type: object }
                constraints: { type: object }
                extra: { type: object }
      responses:
        '200':
          description: Successful response.
  /viam.service.motion.v1.MotionService/MoveOnMap:
    post:
      summary: Viam Move On Map
      description: Move a base component to a destination on a SLAM map.
      operationId: moveOnMap
      tags: [Motion]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, destination, component_name, slam_service_name]
              properties:
                name: { type: string }
                destination: { type: object }
                component_name: { type: object }
                slam_service_name: { type: object }
                motion_configuration: { type: object }
                obstacles: { type: array, items: { type: object } }
      responses:
        '200':
          description: Successful response.
  /viam.service.motion.v1.MotionService/MoveOnGlobe:
    post:
      summary: Viam Move On Globe
      description: Move a base component to a destination on the globe using GPS coordinates.
      operationId: moveOnGlobe
      tags: [Motion]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, destination, component_name, movement_sensor_name]
              properties:
                name: { type: string }
                destination: { type: object }
                heading: { type: number }
                component_name: { type: object }
                movement_sensor_name: { type: object }
                obstacles: { type: array, items: { type: object } }
                motion_configuration: { type: object }
      responses:
        '200':
          description: Successful response.
  /viam.service.motion.v1.MotionService/GetPose:
    post:
      summary: Viam Get Pose
      description: Retrieve the pose of a component relative to a destination frame.
      operationId: getPose
      tags: [Motion]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, component_name]
              properties:
                name: { type: string }
                component_name: { type: object }
                destination_frame: { type: string }
                supplemental_transforms: { type: array, items: { type: object } }
      responses:
        '200':
          description: Successful response.
  /viam.service.motion.v1.MotionService/StopPlan:
    post:
      summary: Viam Stop Plan
      description: Stop a running motion plan.
      operationId: stopPlan
      tags: [Motion]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, component_name]
              properties:
                name: { type: string }
                component_name: { type: object }
      responses:
        '200':
          description: Successful response.
  /viam.service.motion.v1.MotionService/ListPlanStatuses:
    post:
      summary: Viam List Plan Statuses
      description: List status of motion plans on the machine.
      operationId: listPlanStatuses
      tags: [Motion]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name: { type: string }
                only_active_plans: { type: boolean }
      responses:
        '200':
          description: Successful response.
  /viam.service.motion.v1.MotionService/GetPlan:
    post:
      summary: Viam Get Plan
      description: Retrieve a motion plan by execution id.
      operationId: getPlan
      tags: [Motion]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, component_name]
              properties:
                name: { type: string }
                component_name: { type: object }
                execution_id: { type: string }
                last_plan_only: { type: boolean }
      responses:
        '200':
          description: Successful response.
  /viam.service.motion.v1.MotionService/DoCommand:
    post:
      summary: Viam Do Command
      description: Model-specific custom commands.
      operationId: doCommand
      tags: [Motion]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, command]
              properties:
                name: { type: string }
                command: { type: object }
      responses:
        '200':
          description: Successful response.
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: key
      description: Viam API key or location secret.

Viam Motion Service API

Documentation

Specifications

Other Resources

OpenAPI Specification