openapi: 3.1.0
info:
  title: Viam Fleet Management API
  description: |
    REST/JSON transcoding of the Viam AppService gRPC API. Manage organizations, locations,
    machines (robots), machine parts, fragments, OAuth apps, and team memberships in the
    viam.app cloud.

    Canonical contract: https://github.com/viamrobotics/api/blob/main/proto/viam/app/v1/app.proto
  version: '2026.05'
  contact:
    name: Viam Support
    url: https://www.viam.com/contact
  x-logo:
    url: https://www.viam.com/favicon.ico
servers:
  - url: https://app.viam.com
    description: Viam production cloud (gRPC + gRPC-Web)
security:
  - ApiKeyAuth: []
tags:
  - name: Organizations
    description: Tenant boundary for Viam — owns locations, machines, members, billing, and registry items.
  - name: Locations
    description: Logical grouping of machines (e.g., a building, site, or robot fleet).
  - name: Machines
    description: A robot or smart machine running viam-server. Composed of one or more parts.
  - name: Machine Parts
    description: A single viam-server process running on a device. A machine can have multiple parts.
  - name: Fragments
    description: Reusable machine configuration snippets, versioned and shareable across orgs.
  - name: Members
    description: Organization membership, invites, and authorizations (RBAC).
  - name: OAuth Apps
    description: OAuth applications registered against a Viam organization for third-party integrations.
  - name: Secrets
    description: Location and machine-part secrets used by SDKs to authenticate.
paths:
  /viam.app.v1.AppService/ListOrganizations:
    post:
      summary: Viam List Organizations
      description: List organizations the caller has access to.
      operationId: listOrganizations
      tags: [Organizations]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  organizations:
                    type: array
                    items: { $ref: '#/components/schemas/Organization' }
  /viam.app.v1.AppService/GetOrganization:
    post:
      summary: Viam Get Organization
      description: Retrieve a single organization by id.
      operationId: getOrganization
      tags: [Organizations]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [organization_id]
              properties:
                organization_id: { type: string }
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  organization: { $ref: '#/components/schemas/Organization' }
  /viam.app.v1.AppService/CreateOrganization:
    post:
      summary: Viam Create Organization
      description: Create a new organization.
      operationId: createOrganization
      tags: [Organizations]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name: { type: string }
      responses:
        '200':
          description: Successful response.
  /viam.app.v1.AppService/UpdateOrganization:
    post:
      summary: Viam Update Organization
      description: Update an organization's name or public namespace.
      operationId: updateOrganization
      tags: [Organizations]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [organization_id]
              properties:
                organization_id: { type: string }
                name: { type: string }
                public_namespace: { type: string }
      responses:
        '200':
          description: Successful response.
  /viam.app.v1.AppService/DeleteOrganization:
    post:
      summary: Viam Delete Organization
      description: Delete an organization.
      operationId: deleteOrganization
      tags: [Organizations]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [organization_id]
              properties:
                organization_id: { type: string }
      responses:
        '200':
          description: Successful response.
  /viam.app.v1.AppService/ListLocations:
    post:
      summary: Viam List Locations
      description: List locations under an organization.
      operationId: listLocations
      tags: [Locations]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [organization_id]
              properties:
                organization_id: { type: string }
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  locations:
                    type: array
                    items: { $ref: '#/components/schemas/Location' }
  /viam.app.v1.AppService/GetLocation:
    post:
      summary: Viam Get Location
      description: Retrieve a single location by id.
      operationId: getLocation
      tags: [Locations]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [location_id]
              properties:
                location_id: { type: string }
      responses:
        '200':
          description: Successful response.
  /viam.app.v1.AppService/CreateLocation:
    post:
      summary: Viam Create Location
      description: Create a new location under an organization.
      operationId: createLocation
      tags: [Locations]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [organization_id, name]
              properties:
                organization_id: { type: string }
                name: { type: string }
                parent_location_id: { type: string }
      responses:
        '200':
          description: Successful response.
  /viam.app.v1.AppService/UpdateLocation:
    post:
      summary: Viam Update Location
      description: Update a location's name or parent location.
      operationId: updateLocation
      tags: [Locations]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [location_id]
              properties:
                location_id: { type: string }
                name: { type: string }
                parent_location_id: { type: string }
      responses:
        '200':
          description: Successful response.
  /viam.app.v1.AppService/DeleteLocation:
    post:
      summary: Viam Delete Location
      description: Delete a location and all machines under it.
      operationId: deleteLocation
      tags: [Locations]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [location_id]
              properties:
                location_id: { type: string }
      responses:
        '200':
          description: Successful response.
  /viam.app.v1.AppService/ListRobots:
    post:
      summary: Viam List Machines
      description: List machines (robots) in a location.
      operationId: listRobots
      tags: [Machines]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [location_id]
              properties:
                location_id: { type: string }
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  robots:
                    type: array
                    items: { $ref: '#/components/schemas/Machine' }
  /viam.app.v1.AppService/GetRobot:
    post:
      summary: Viam Get Machine
      description: Retrieve a machine by id.
      operationId: getRobot
      tags: [Machines]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [id]
              properties:
                id: { type: string }
      responses:
        '200':
          description: Successful response.
  /viam.app.v1.AppService/NewRobot:
    post:
      summary: Viam Create Machine
      description: Create a new machine under a location.
      operationId: newRobot
      tags: [Machines]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [location, name]
              properties:
                location: { type: string }
                name: { type: string }
      responses:
        '200':
          description: Successful response.
  /viam.app.v1.AppService/UpdateRobot:
    post:
      summary: Viam Update Machine
      description: Update a machine's name or location.
      operationId: updateRobot
      tags: [Machines]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [id]
              properties:
                id: { type: string }
                name: { type: string }
                location: { type: string }
      responses:
        '200':
          description: Successful response.
  /viam.app.v1.AppService/DeleteRobot:
    post:
      summary: Viam Delete Machine
      description: Delete a machine.
      operationId: deleteRobot
      tags: [Machines]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [id]
              properties:
                id: { type: string }
      responses:
        '200':
          description: Successful response.
  /viam.app.v1.AppService/GetRobotParts:
    post:
      summary: Viam Get Machine Parts
      description: List parts (viam-server processes) that make up a machine.
      operationId: getRobotParts
      tags: [Machine Parts]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [robot_id]
              properties:
                robot_id: { type: string }
      responses:
        '200':
          description: Successful response.
  /viam.app.v1.AppService/GetRobotPart:
    post:
      summary: Viam Get Machine Part
      description: Retrieve a single machine part.
      operationId: getRobotPart
      tags: [Machine Parts]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [id]
              properties:
                id: { type: string }
      responses:
        '200':
          description: Successful response.
  /viam.app.v1.AppService/NewRobotPart:
    post:
      summary: Viam Create Machine Part
      description: Create a new machine part.
      operationId: newRobotPart
      tags: [Machine Parts]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [robot_id, part_name]
              properties:
                robot_id: { type: string }
                part_name: { type: string }
      responses:
        '200':
          description: Successful response.
  /viam.app.v1.AppService/MarkPartForRestart:
    post:
      summary: Viam Restart Machine Part
      description: Schedule a restart for a machine part.
      operationId: markPartForRestart
      tags: [Machine Parts]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [part_id]
              properties:
                part_id: { type: string }
      responses:
        '200':
          description: Successful response.
  /viam.app.v1.AppService/GetRobotPartLogs:
    post:
      summary: Viam Get Machine Part Logs
      description: Retrieve logs from a machine part.
      operationId: getRobotPartLogs
      tags: [Machine Parts]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [id]
              properties:
                id: { type: string }
                errors_only: { type: boolean }
                filter: { type: string }
      responses:
        '200':
          description: Successful response.
  /viam.app.v1.AppService/ListFragments:
    post:
      summary: Viam List Fragments
      description: List configuration fragments in an organization.
      operationId: listFragments
      tags: [Fragments]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [organization_id]
              properties:
                organization_id: { type: string }
                show_public: { type: boolean }
      responses:
        '200':
          description: Successful response.
  /viam.app.v1.AppService/CreateFragment:
    post:
      summary: Viam Create Fragment
      description: Create a new configuration fragment.
      operationId: createFragment
      tags: [Fragments]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, organization_id, config]
              properties:
                name: { type: string }
                organization_id: { type: string }
                config: { type: object }
                visibility: { type: string, enum: [private, public] }
      responses:
        '200':
          description: Successful response.
  /viam.app.v1.AppService/GetFragment:
    post:
      summary: Viam Get Fragment
      description: Retrieve a fragment by id.
      operationId: getFragment
      tags: [Fragments]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [id]
              properties:
                id: { type: string }
      responses:
        '200':
          description: Successful response.
  /viam.app.v1.AppService/UpdateFragment:
    post:
      summary: Viam Update Fragment
      description: Update an existing fragment.
      operationId: updateFragment
      tags: [Fragments]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [id]
              properties:
                id: { type: string }
                name: { type: string }
                config: { type: object }
                visibility: { type: string }
      responses:
        '200':
          description: Successful response.
  /viam.app.v1.AppService/DeleteFragment:
    post:
      summary: Viam Delete Fragment
      description: Delete a fragment.
      operationId: deleteFragment
      tags: [Fragments]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [id]
              properties:
                id: { type: string }
      responses:
        '200':
          description: Successful response.
  /viam.app.v1.AppService/ListOrganizationMembers:
    post:
      summary: Viam List Organization Members
      description: List members and pending invites for an organization.
      operationId: listOrganizationMembers
      tags: [Members]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [organization_id]
              properties:
                organization_id: { type: string }
      responses:
        '200':
          description: Successful response.
  /viam.app.v1.AppService/CreateOrganizationInvite:
    post:
      summary: Viam Invite Organization Member
      description: Invite a user to an organization with one or more authorizations.
      operationId: createOrganizationInvite
      tags: [Members]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [organization_id, email]
              properties:
                organization_id: { type: string }
                email: { type: string }
                authorizations: { type: array, items: { type: object } }
      responses:
        '200':
          description: Successful response.
  /viam.app.v1.AppService/DeleteOrganizationMember:
    post:
      summary: Viam Remove Organization Member
      description: Remove a member from an organization.
      operationId: deleteOrganizationMember
      tags: [Members]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [organization_id, user_id]
              properties:
                organization_id: { type: string }
                user_id: { type: string }
      responses:
        '200':
          description: Successful response.
  /viam.app.v1.AppService/CreateOAuthApp:
    post:
      summary: Viam Create Oauth App
      description: Register a new OAuth application against an organization.
      operationId: createOAuthApp
      tags: [OAuth Apps]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [organization_id, client_name]
              properties:
                organization_id: { type: string }
                client_name: { type: string }
                redirect_uris: { type: array, items: { type: string } }
      responses:
        '200':
          description: Successful response.
  /viam.app.v1.AppService/ListOAuthApps:
    post:
      summary: Viam List Oauth Apps
      description: List OAuth applications registered under an organization.
      operationId: listOAuthApps
      tags: [OAuth Apps]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [organization_id]
              properties:
                organization_id: { type: string }
      responses:
        '200':
          description: Successful response.
  /viam.app.v1.AppService/CreateLocationSecret:
    post:
      summary: Viam Create Location Secret
      description: Create a new location-level secret used by SDKs to connect.
      operationId: createLocationSecret
      tags: [Secrets]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [location_id]
              properties:
                location_id: { type: string }
      responses:
        '200':
          description: Successful response.
  /viam.app.v1.AppService/DeleteLocationSecret:
    post:
      summary: Viam Delete Location Secret
      description: Revoke a location secret.
      operationId: deleteLocationSecret
      tags: [Secrets]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [location_id, secret_id]
              properties:
                location_id: { type: string }
                secret_id: { type: string }
      responses:
        '200':
          description: Successful response.
  /viam.app.v1.AppService/GetRobotAPIKeys:
    post:
      summary: Viam Get Machine Api Keys
      description: List API keys with access to a machine.
      operationId: getRobotAPIKeys
      tags: [Secrets]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [robot_id]
              properties:
                robot_id: { type: string }
      responses:
        '200':
          description: Successful response.
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: key
      description: Viam API key id and key value sent as gRPC metadata (key_id + key).
  schemas:
    Organization:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        public_namespace: { type: string }
        created_on: { type: string, format: date-time }
    Location:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        organization: { type: string }
        parent_location_id: { type: string }
        auth: { type: object }
        created_on: { type: string, format: date-time }
    Machine:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        location: { type: string }
        last_access: { type: string, format: date-time }
        created_on: { type: string, format: date-time }