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.