Viam Motion API

openapi: 3.2.0
info:
  title: Viam Service Motion 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.