---
title: "Provision"
method: POST
path: "/provision"
tags: ["robots"]
---

# Provision

`POST /provision`

## Request

- Base URL: `https://api.os3robotics.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.os3robotics.com/provision`
- Auth: none declared

## Request body

- ProvisionRequest
  - `certificate` string, required
  - `payload` string, required
  - `signature` string, required

## Response `200`

Successful Response

- RobotCredential: POST /provision and POST /robots/rotate: the robot and its new credential, shown once. The credential it replaced stays valid until the next rotation. ``trace``: the organisation's trace salt and consent block.
  - `id` string, uuid, required
  - `tenant_id` string, uuid, required
  - `workspace_id` string, uuid, required
  - `name` string, required
  - `embodiment` string, required
  - `action_space_id` string, required
  - `wire_contract_version` string, required
  - `camera_shapes` object, required
  - `controller_api_version` string, required
  - `calibration_sha256` string, nullable, required
  - `serial` string, nullable, required
  - `status` 'registered' | 'connected' | 'revoked', required
  - `credential_issued_at` string, date-time, required
  - `created_at` string, date-time, required
  - `last_seen_at` string, date-time, nullable, required
  - `revoked_at` string, date-time, nullable, required
  - `deleted_at` string, date-time, nullable
  - `specs` RobotSpecs, required: What the robot agent reports on its heartbeat (the registered identity, embodiment, action_space_id and the policy's camera_shapes, are the Robot's own fields).
    - `dof` integer, nullable
    - `cameras` object
    - `agent_version` string, nullable
    - `firmware_version` string, nullable
    - `rig` string, nullable
  - `live` RobotLive, required
    - `online` boolean, required
    - `endpoint_id` string, uuid, nullable, required
    - `latency_ms` number, nullable, required
    - `voice` VoiceHealth: The robot's voice fallback state at its heartbeat: the current rung of its degradation ladder, backend names and reasons, never audio or text.
      - `rung` 'full' | 'cascade' | 'local_only' | 'voice_paused' | 'audio_lost', required
      - `backend` string, nullable
      - `unhealthy_backends` string[]
      - `harness_dead` boolean
      - `reason` string, nullable
  - `connection` RobotConnection, required: How the robot reaches its endpoints: `direct_tls`, or `tailnet` once it joined OS3's tailnet (POST /robots/tailnet: its node's name and its tenant's robot tag).
    - `mode` 'direct_tls' | 'tailnet', required
    - `tailnet_node` string, nullable, required
    - `tailnet_ip` string, nullable, required
    - `tailnet_tag` string, nullable, required
  - `capabilities` RobotCapabilities, required
    - `teleop` boolean
  - `credential` string, required
  - `trace` RobotTrace, required: What the robot's harness traces take from its organisation: ``salt`` is the organisation's trace salt for trace ids (never logged), ``consent`` its consent block, as the gateway stamps it, without its ``vendor``, which each record names (its model's).
    - `salt` string, required
    - `consent` object, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/os3robotics/apis/os3-api.md) - [All operations](https://skmtc.dev/os3robotics/apis/os3-api/llms.txt) - [OpenAPI document](https://skmtc.dev/os3robotics/apis/os3-api/revisions/af32cd4f14bb?raw)