---
title: "Connect"
method: POST
path: "/connect"
tags: ["robots"]
---

# Connect

`POST /connect`

## 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/connect`
- Auth: HTTP bearer

## Request body

- ConnectRequest: Exactly one of `handshake` (the robot's full handshake record) and `identity`.
  - `endpoint_id` string, uuid, required
  - `handshake` HandshakeRecord: What a policy server declares when a controller connects; every field is required.
    - `checkpoint_sha256` string, required
    - `action_space_id` string, required
    - `action_dim` integer, required
    - `wire_contract_version` string, required
    - `camera_shapes` object, required
    - `controller_api_version` string, required
    - `endpoint_type` 'vla_policy' | 'planner_llm' | 'harness' | 'llm_vllm' | 'llm_sglang', required
    - `observation` ObservationSchema
      - `schema_version` 'os3.observation_schema.v1', required
      - `modalities` object, required
    - `action_adapter` ActionAdapter
      - `schema_version` 'os3.action_adapter.v1', required
      - `action_space_id` string, required
      - `names` string[], required
      - `units` string[], required
      - `relative_channels` integer[]
      - `relative_to` string, nullable
    - `model_ref` string, required
    - `min_controller` string, nullable
  - `identity` ConnectIdentity: What the robot is, without a model: its action space, cameras, controller API and endpoint type. It is checked against the model its endpoint serves now.
    - `action_space_id` string, required
    - `action_dim` integer, required
    - `wire_contract_version` string, required
    - `camera_shapes` object, required
    - `controller_api_version` string, required
    - `endpoint_type` 'vla_policy' | 'planner_llm' | 'harness' | 'llm_vllm' | 'llm_sglang', required
    - `observation` ObservationSchema
      - `schema_version` 'os3.observation_schema.v1', required
      - `modalities` object, required
    - `action_adapter` ActionAdapter
      - `schema_version` 'os3.action_adapter.v1', required
      - `action_space_id` string, required
      - `names` string[], required
      - `units` string[], required
      - `relative_channels` integer[]
      - `relative_to` string, nullable

## Response `200`

Successful Response

- ConnectGrant
  - `grant_id` integer, required
  - `robot_id` string, uuid, required
  - `endpoint_id` string, uuid, required
  - `url` string, required
  - `auth_scheme` string
  - `token` string, required
  - `token_expires_at` string, date-time, required
  - `tls_pin_sha256` string, nullable, required
  - `max_size` integer, required
  - `required_task_suffix` string, required
  - `server` 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)